Enterprise COBOL and Java Interoperation

Nick Tindall
Stephen Miller
August 14, 2003
Objectives for IBM Object Oriented COBOL
• Enable fine-grained interoperation of COBOL and Java within an address
space, both:
– COBOL invocation of Java
– Java invocation of COBOL
• Complement existing COBOL:Java interoperation
– mediated by middleware, based on connectors
– COBOL and Java running in different address spaces or machines
– only for COBOL transactions
• Fine-grained interoperation (interlanguage communication) provides:
– better performance
– use of non-transactional COBOL
• Improve integration of COBOL with WebSphere Application Server
– COBOL client invocation of enterprise beans
– Future support for COBOL execution within WebSphere server regions

August, 2003 2
Example scenarios
• Enhance existing COBOL routines to access new business logic written in
Java
• Write new business logic in Java, access existing libraries of production
COBOL routines
• New business logic written in Java can invoke COBOL routines to process
existing COBOL data in QSAM/VSAM files
• COBOL programs can invoke Java for full-function XML parsing
– (use new direct COBOL support for high-speed parsing of input XML
documents!)
• COBOL programs can invoke methods (directly) on enterprise beans
running in a WebSphere server region
- or -
COBOL programs can invoke Java routines, which act as J2EE clients
accessing enterprise beans
• Write new IMS message processing or database logic in Java, mixing with
COBOL to leverage existing IMS COBOL applications and IMS
programming skills

August, 2003 3
Prerequisite technologies for Java interoperation

• Basic C interoperability and DLL support

• Basic development-time and run-time support for z/OS Unix
• Multi-thread enablement
• Asynchronous signal toleration
• Unicode
• Function pointers
• IEEE floating point

August, 2003 4
Delivery
IBM COBOL for OS/390 & VM
• C interoperability and DLL support
• Basic development-time and run-time support for z/OS Unix
IBM Enterprise COBOL for z/OS and OS/390 V3R1, GA 11/2001
• Multi-thread enablement
• Asynchronous signal toleration
• Unicode
• Function pointers
• Java interoperation, USS and batch environments (BPXBATCH)
• COBOL client code invoking enterprise beans running in WebSphere 390
IBM Enterprise COBOL for z/OS and OS/390 V3R2, GA 9/2002
• Java interoperation in IMS environment
• COBOL class with "main" method
• Parameterized JVM initialization - user-specified JVM options
• OPTIMIZE option for programs using OO syntax for Java interoperability
• Execution of OO applications from batch JCL

August, 2003 5
Unicode
• Basic run-time Unicode datatype support
– USAGE NATIONAL clause
– PICTURE character N mapped to UTF-16
– Unicode literals - N'Straße', N'αβγ', NX'03B103B203B3'
– Implicit conversions in mixed operations
– Binary collation
• CODEPAGE() compiler option - specifies EBCDIC code page for:
– alphanumeric and DBCS data items at run time
– alphanumeric, national, and DBCS literals in the source program
• NSYMBOL(NATIONAL|DBCS)
– provides compatibility with existing DBCS support
• Enable:
– Exchange of String data between Java and COBOL
– Invocation of Java methods with Unicode method names
– COBOL methods with Unicode method names
– Override/overload Java methods that have Unicode method names

August, 2003 6
Java Interoperation

• Existing OO COBOL syntax re-based on Java, and the Java Native

Interface (JNI)
– COBOL INVOKE statement maps onto Java JNI calls
– COBOL class and method definitions define Java native
methods
– SOM-based OO COBOL support removed
- SOMObjects has been removed from z/OS
• Documentation and assistance in mapping Java data types to/from
COBOL
• Support for JNI programming in COBOL
• COBOL COPY file analogous to jni.h, enables access to JNI callable
services
• Java prerequisite: IBM Java 2 Technology Edition SDK 1.3.0

August, 2003 7
Client-side syntax
Declare referenced class and full external class name
Configuration section.
Repository paragraph.
Class Employee is 'com.acme.Employee'.
Declare object reference
01 anEmployee usage object reference Employee.
Invoke instance method
Invoke anEmployee 'payRaise'
using by value amount
Invoke static method
Invoke Employee 'getNbrEmployees'
returning totalEmployees
Create instance object
Invoke Employee New using by value id
returning anEmployee

August, 2003 8
Interoperable data types for method parameters

Java COBOL
boolean 01 B pic X.
88 B-false value X'00'.
88 B-true value X'01' through X'FF'.
byte Pic X or Pic A
short Pic S9(4) usage binary or comp-5
int Pic S9(9) usage binary or comp-5
long Pic S9(18) usage binary or comp-5
float Usage comp-1
double Usage comp-2
char Pic N usage national
class types (object references) Usage object reference class-name
including strings and arrays

August, 2003 9
Access JNI services from COBOL
• Function pointers for JNI services are in the JNI Environment Structure
Access JNI Environment pointer
• New special register JNIEnvPtr
Access JNI Environment Structure and JNI callable services
Linkage section.
COPY 'JNI.cpy'
Procedure division.
Set address of JNIEnv to JNIEnvPtr
Set address of JNINativeInterface to JNIEnv

Check if an exception has been thrown by a Java routine

Invoke aJavaObject N'someJavaMethodOnΕλλάδα'
Call ExceptionOccurred !this is a JNI function pointer
using by value JNIEnvPtr
returning exceptionObject
If exceptionObject not = null
Display 'Caught an unexpected exception'
Call ExceptionClear using by value JNIEnvPtr
Invoke exceptionObject 'PrintStackTrace'
Goback
End-if

August, 2003 10
JNI services for string data
• Unicode-oriented JNI services for Strings, part of the standard SDK:
– NewString
– GetStringLength
– GetStringChars
– ReleaseStringChars
• Access these services with CALL function-pointer statements, using
function pointers in the JNI Environment Structure

• EBCDIC-oriented services for Strings, provided by IBM Java 2 SDK

for z/OS as an extension to the standard Sun SDK:
– NewStringPlatform
– GetStringPlatformLength
– GetStringPlatform
• These services are DLLs, access them with CALL 'literal' statements

August, 2003 11
Use of S/390 JNI services – EBCDIC string data
Create a string object in COBOL, and pass it to Java
Local-storage section.
01 empName pic X(50) value z'Tom Ross'.
01 empNameObj usage object reference jstring.
Procedure division.
Call 'NewStringPlatform'
using by value JNIEnvp
address of empName
address of empNameObj
0
returning rc
Invoke SHAREproject 'SetIBMRep'
using by value empNameObj

August, 2003 12
Use of JNI services - arrays
COBOL processing of an integer array passed from Java …
Local-storage section.
01 IdArrayPtr usage pointer.
Linkage section.
COPY JNI.
01 IdArrayObj usage object reference jintArray.
01 IdArray.
02 IdElement pic s9(9) comp-5 occurs 100 times.
Procedure division using IdArrayObj.
Set address of JNIEnv to JNIEnvPtr
Set address of JNINativeInterface to JNIEnv
Call GetIntArrayElements
using by value JNIEnvPtr, IdArrayObj, 0
returning IdArrayPtr
Set address of IdArray to IDArrayPtr
* Process array of binary integers from COBOL data structure

August, 2003 13
Compiler implementation: map COBOL OO syntax onto
a sequence of generated JNI calls

Syntax:
Invoke anEmployee 'payRaise' using by value amount
Implementation (under the covers):
1. Construct argument list
– automatically convert any floating point arguments to/from IEEE float
– automatically handle implicit arguments required by JNI
2. Acquire class object, via GetObjectClass or FindClass
3. Convert method name ('payRaise') to Unicode
4. Construct method signature: null-terminated ASCII string '(I)V'
5. Call GetMethodId passing JNI env, class object, method name,
signature
6. Call CallVoidMethod passing env, object, method id, and arguments

August, 2003 14
COBOL native method - syntax
Identification Division.
Class-id. Manager inherits Employee.
Environment Division.
Configuration section.
Repository.
Class Manager is 'com.acme.Manager'
Class Employee is 'com.acme.Employee'.
Identification division.
Object.
Procedure Division.
Identification Division.
Method-id. 'Hire'.
Data Division.
Linkage section.
01 anEmployee usage object reference Employee.
Procedure Division using anEmployee.
…
End method 'Hire'.
End Object.
End class Manager.
August, 2003 15
COBOL classes
• OBJECT paragraph - defines object instance methods
• FACTORY paragraph - defines static methods
• COBOL classes can inherit from COBOL or Java classes
• Java classes can inherit from COBOL classes
• Methods can override inherited methods
• Methods can be overloaded
• Method names can be formed using Unicode characters, per Java
rules
• Method parameters must be COBOL data types that map to Java
data types

August, 2003 16
COBOL methods can be overloaded
Identification Division.
Class-id. Account inherits Base.
…
Identification Division.
Method-id. 'credit'. Same method name

Data Division.
Linkage section.
01 amount pic S9(9) binary. Different parameter datatypes

Procedure Division using amount.

…
End method 'credit'
Identification Division.
Method-id. 'credit'.
Data Division.
Linkage section.
01 amount comp-2.
Procedure Division using amount.
…
End method 'credit'.
End Object.
End class Account.
August, 2003 17
Accessing procedural COBOL code from Java

• Code in COBOL classes can CALL procedural COBOL code

• Write a COBOL wrapper class for the procedural COBOL program
• Define a Factory method containing a CALL to the COBOL program
• Access COBOL from Java using a static method invocation, e.g.
rc=Wrapper.callCob1(arg1,arg2);

A.java Wrapper.cbl Cob1.cbl

Factory. Identification division.
Identification division. Program-id. 'Cob1'.
Method-id. 'CallCob1'.
rc=Wrapper.callCob1(arg1,arg2);
Procedure division using by value arg1,arg2.
Call 'Cob1' using arg1, arg2

August, 2003 18
Compile and link of COBOL class definition

• Compile of COBOL class definition generates two artifacts:

– COBOL object program implementing native method(s)
– Java class source that declares the native methods and
manages DLL loading
• COBOL object program is linked to form DLL: libclassname.so
• Java class is compiled (with javac) to form classname.class

August, 2003 19
 Manager.cbl
Identification division.
Class-id. Manager inherits Employee.
…
End class Manager.

cob2

Manager.java Manager.o
public class Manager
extends Employee {
public native void Hire(…);
static {
System.load Library(…);}
}

Manager.class javac libManager.so linkedit

August, 2003 20
Structuring mixed COBOL and Java applications

1. Application can start with a COBOL program, use classes written in

COBOL or Java
2. Application can start with main method of a Java class
– main method must be public, static, void with a single parameter
of type java.lang.String[]
3. Application can start with main method of a COBOL class
– main must be a Factory method with no RETURNING clause,
with a single parameter that is an object reference of type array
of java.lang.String

August, 2003 21
Executing COBOL and Java applications
COBOL and Java mixed applications are designed primarily to run
under z/OS Unix System Services (USS) environment, with
application components residing in the Hierarchical File System
(HFS)

Recommendations:
• Execute COBOL:Java applications that start with a COBOL
program:
– from a Unix shell command prompt, or
– from JCL or TSO/E, using the BPXBATCH utility
• Execute COBOL:Java applications that start with the main method
of a Java or COBOL class:
– with the java command from a Unix shell command prompt, or
using BPXBATCH from batch JCL or TSO/E
– in an IMS Java dependent region (see below)

August, 2003 22
Executing COBOL and Java applications…

In limited cases, COBOL:Java applications can also be executed from

standard JCL (EXEC PGM=modname). To do this:
• the application must start with a COBOL program, linked into a
PDSE instead of HFS
• the .class files and DLLs for classes still must reside in HFS
• specify CLASSPATH, PATH, LIBPATH, COBJVMINITOPTIONS
environment variables in a file
• specify the environment variable file using LE ENVAR option and
_CEE_ENVFILE
• specify the POSIX(ON) run-time option
• use DD statements JAVAOUT, JAVAERR, JAVAIN for the standard
Java streams

August, 2003 23
WebSphere integration - WAS client binding for
COBOL

• COBOL applications can invoke methods on enterprise beans

running in WebSphere servers
• COBOL client uses the Java programming model
– Java Naming and Directory Interface (JNDI)
– Java ORB

August, 2003 24
Java client (from J2EE Developer's Guide)

Try {
Context initial = new InitialContext();
Object objref = initial.lookup("MyConverter");
ConverterHome home =
(ConverterHome)PortableRemoteObject.narrow(
objref,ConverterHome.class);
Converter currencyConverter = home.create();
double amount =
CurrencyConverter.dollarToYen(100.00);
…

August, 2003 25
COBOL client:

Invoke InitialContext New returning initialCtx

Perform ErrorCheck

Move z'MyConverter' to stringBuf

Call 'NewStringPlatform' using by value JNIEnvPtr,
address of stringBuf, address of jstring1, 0
Invoke initialCtx 'lookup' using by value jstring1
returning objref

Move z'ConverterHome' to stringBuf

Call FindClass using by value env, address of stringBuf
returning classObj
Invoke PortableRemoteObject 'narrow'
using by value objref, classObj
returning home

Invoke home 'create' returning currencyConverter

Invoke currencyConverter 'dollarToYen' using by value +100.00E+0

returning amount

August, 2003 26
COBOL and Java interoperation under IMS
• IMS applications can now be written in a mixture of COBOL and Java
• Applications execute in IMS Java dependent regions
– JMP - Java Message Processing region
– JBP - Java Batch Processing region
• Prerequisites:
– IMS Version 8, or
– IMS Version 7 with PTFs for APAR PQ53944 (UQ61540) and PQ54039
(UQ61590)
– Java 2 Technology Edition SDK 1.3.1, which provides persistent
reusable JVM for transaction processing
• Application front-end must be main method of a Java or COBOL class
• Java components access IMS databases and message processing services
using IMS Java class library
• COBOL components use traditional DL/I calls, using the AIB interface, e.g.
CALL 'CEETDLI' using GU, AIB, input-area
• See IMS Version 8 Java User's Guide, and new Enterprise COBOL
Programming Guide
August, 2003 27
Getting started with COBOL and Java interoperability
• Ensure you have the Java 2 Technology Edition SDK installed
– SDK 1.3.1 if you will be running under IMS
– SDK 1.3.0 or 1.3.1 otherwise
• If you are running z/OS V1R1 or OS/390 V2R10, ensure that OS/390
Support for Unicode (HUNI2A0) is installed.
• For either OS/390 or z/OS systems, ensure that the Unicode Conversion
Services are configured for COBOL use. At minimum, configure conversion
between these pairs of CCSIDs:
– 1140 to/from 1200
– 1140 to 1208
– 1200 to 1208
• Configure these conversions with the default technique-search-order
'RECLM'.
• See the Enterprise COBOL V3R2 Customization Guide for details and
sample JCL for configuring Unicode Conversion Services for COBOL
• See the sample OO application and makefile that is shipped with COBOL in
/usr/lpp/cobol/demo/oosample. Try compiling and running this application.
August, 2003 28