Calling Procedural COBOL from Java

Chapter 1: Before You Start

This chapter introduces the facilities Server Express provides for using COBOL and Java components together in a distributed computing environment and presents important information you should be familiar with before starting.

1.1 Introduction

There are two ways of using COBOL and Java together:

The procedural model, which allows you to call procedural COBOL from Java (see the chapter Calling Procedural COBOL from Java).
The Object model, which allows you to call Java from COBOL and Object COBOL from Java (see the chapters Calling Java from COBOL and Calling Object COBOL from Java).

You can also wrap existing COBOL business logic as an Enterprise JavaBean. For further details see the chapter Calling Object COBOL from Java.

Java itself provides access to other technologies, such as Remote Method Invocation (RMI) and Java Naming and Directory Interface (JNDI) which enable you to distribute objects across different machines.

You need to have at least a basic knowledge of the Java language to be able to use this technology effectively. Sun's Java site is a good starting place.

1.2 Preparing to Use Java and COBOL Together

The following subsections describe all the things you need to do before using Java and COBOL together. Some items apply only when calling COBOL from Java, and some apply only when calling Java from COBOL.

1.2.1 Setting Up the COBOL and Java Environments

You need a Java run-time system on any machine which is going to execute Java applications. If you are going to develop mixed Java and COBOL applications, you will need a Java Virtual Machine (JVM), which provides both a development environment and a run-time environment. You can obtain a Java Virtual Machine from your operating system vendor.

If your platform supports multiple JVMs, you can switch between JVMs using the following methods:

Change the default JVM set when Server Express was installed by running the script java_setup. Use this method when you are sure that you want to change the default JVM on a more or less permanent basis. To run the script:
1. Login as superuser.
2. Set the COBDIR environment variable to the directory where Server Express is installed.
3. Change directory to $COBDIR/bin.
4. Enter: java_setup
5. When requested, select the version of Java that you want to be the default.

Set the environment variable COBJVM. Use this method to override the default value, for example, if you are developing new applications with a later JVM, while still working with existing applications developed using an earlier JVM.

The table below shows which JVM and COBJVM setting you need for your operating system.

Operating System	Java Vendor	JVM Version	COBJVM Setting
AIX	IBM	1.2.n	ibm_122
AIX	IBM	1.3.n	ibm_130
UnixWare	SCO	1.2.n	unx_122
SunOS	Sun	1.2.n	sun_122
SunOS	Sun	1.3.n	sun_130

HP-UX:
If your platform is HP-UX, you cannot change JVMs using the COBJVM environment variable. Instead you can change JVMs by adding a PATH setting to change the directory in which Server Express searches for the Java environment. See the section Environment Variable Settings for HP-UX.

Before you start writing COBOL and Java programs which interact, you need to set some environment variables for the COBOL and Java run-time systems. The exact settings of these environment variables depend on the platform you are using. The list below describes the required settings in generic terms, while the following sections show example settings for the different platforms:

Java's CLASSPATH must include $COBDIR/lib/mfcobol.jar
PATH must include the directory containing the Java environment.
If you are using the Sun JVM, you need to add a Sun subdirectory to PATH.
The operating system's shared library path must include the directory containing libjava. This is often found in a subdirectory of Java's jre/lib directory, although the name of this directory is specific to each platform. On some platforms, you might need to specify more than one directory for this, for example, an additional directory containing the Java native threading support.
To be able to compile Java source, COBCPY must specify $COBDIR/cpylib.
If you are planning to deploy Object COBOL Enterprise JavaBeans (EJBs) to WebSphere on the AIX platform, you might need to set the COBMAINSTACK environment variable. This is because WebSphere requires a large amount of stack space during the process of starting the EJB server. You should set it to at least 256Kb.

1.2.1.1 Environment Variable Settings for Solaris

This section lists example environment variable settings that enable COBOL/Java working on Solaris platforms using Version 1.2.2 of the Sun JVM. You will need to change the settings given below to specify the relevant directories on your system.

export JH=$HOME/java1.2
export COBDIR=server_express_directory
export PATH=$JH/bin:$PATH
export PATH=$COBDIR/bin:$PATH
export LD_LIBRARY_PATH=$JH/jre/lib/pfrm:$COBDIR/lib:$LD_LIBRARY_PATH
export CLASSPATH=$COBDIR/lib/mfcobol.jar:$JH/jre/lib/rt.jar:.
export COBCPY=$COBDIR/cpylib
export COBJVM=sun_122  
export PATH=/usr/openwin/bin:$PATH

where:

pfrm is i386 for the Intel platform or sparc for the SPARC platform

server_express_directory is the directory in which Server Express is installed.

1.2.1.2 Environment Variable Settings for AIX

This section lists example environment variable settings that enable COBOL/Java working on AIX platforms using Version 1.3 of the IBM JVM. You will need to change the settings given below to specify the relevant directories on your system.

export JH=/usr/java130
export COBDIR=server_express_directory
export PATH=/usr/java_dev130/jre/sh:/usr/java130/sh:$PATH
export PATH=$COBDIR/bin:$PATH
export LIBPATH=$JH/jre/bin/classic:$JH/jre/bin:$COBDIR/lib:$LIBPATH
export CLASSPATH=$COBDIR/lib/mfcobol.jar:/usr/java130/jre/lib/rt.jar:.
export COBCPY=$COBDIR/cpylib
export COBJVM=ibm_130
export COBMAINSTACK=262144

where server_express_directory is the directory in which Server Express is installed.

1.2.1.3 Environment Variable Settings for UnixWare

This section lists example environment variable settings that enable COBOL/Java working on UnixWare platforms. There is no setting for COBJVM because the installation process will already have set it for version 1.2.2, the only version supported. You will need to change the settings given below to specify the relevant directories on your system.

export JH=/usr/java2
export COBDIR=server_express_directory
export PATH=$JH/bin:$PATH
export PATH=$COBDIR/bin:$PATH
export LD_LIBRARY_PATH=$JH/jre/lib/x86at/:$JH/jre/lib/x86at/classic:
$JH/jre/lib/x86at/native_threads:$COBDIR/lib:$LD_LIBRARY_PATH
export CLASSPATH=$COBDIR/lib/mfcobol.jar:$JH/jre/lib/rt.jar:.
export COBCPY=$COBDIR/cpylib
export PATH=/usr/X/bin:$PATH

where server_express_directory is the directory in which Server Express is installed.

1.2.1.4 Environment Variable Settings for HP-UX

This section lists example environment variable settings that enable COBOL/Java working on HP-UX platforms, using the default JVM which was selected when Server Express was installed. You will need to change the settings given below to specify the relevant directories on your system.

export JH=/usr/java1.2
export COBDIR=server-express-directory
export PATH=$JH/bin:$PATH
export PATH=$COBDIR/bin:$PATH
export SHLIB_PATH=$JH/jre/lib/PA_RISC:$JH/jre/lib/PA_RISC/hotspot:
$JH/jre/lib/PA_RISC/native_threads:$COBDIR/lib:$SHLIB_PATH
export CLASSPATH=$COBDIR/lib/mfcobol.jar:$JH/jre/lib/rt.jar:.
export COBCPY=$COBDIR/cpylib
export PATH=/usr/X/bin:$PATH

where server-express-directory is the directory in which Server Express is installed.

To change to a different JVM, add a PATH setting that points to the directory where the Java environment for that JVM is located. The line takes the form:

      export PATH=$COBDIR/bin/jdkn.n:$PATH

where n.n is 1.2 for JVM Version 1.2.n or 1.3 for JVM Version 1.3.n.. This line must appear after the line:

      export PATH=$COBDIR/bin:$PATH

To revert to the default JVM, just remove or comment out the line.

1.2.2 Compiler Directives for COBOL Programs

Any COBOL program which is going to call Java must be compiled with the following directive:

ooctrl"+p-f"

This does two things:

Adds type information to invoke statements, which the COBOL run-time system needs in order to convert data correctly between the COBOL and Java domains
Prevents the Compiler from folding method names it invokes to lower case - Java method names are case-sensitive

1.2.3 Working with Net Express

The easiest (and recommended) way of writing COBOL and Java components is to develop your applications on Net Express, then to publish the result to your target UNIX system. Working in this way enables you to take advantage of Net Express features such as the Class Wizard and Method Wizard, which greatly simplify the process of creating COBOL classes. This book assumes that you are developing your COBOL and Java applications on Net Express using the Class and Method Wizards, then publishing the results to your UNIX system.

For more information on Net Express, see the section Net Express and Server Express in your Getting Started.

1.2.4 The Java/COBOL Application Launcher

The Java/COBOL application launcher is used to launch a Java application from a COBOL run-time environment. You should use the Java/COBOL application launcher instead of your usual Java application launcher as it sets up your environment to correctly manage both the COBOL run-time system and the Java Virtual Machine.

The command to invoke the Java/COBOL application launcher can take one of two formats:

cobjrun [options] class [arguments]

or:

cobjrun -jar [options] jarfile [arguments]

where the parameters are:

`options`	The options you would normally specify to your Java application launcher.
`class`	The name of the class to be invoked. If the Java/COBOL application launcher cannot find a Java class of this name, it tries to find a COBOL program of the same name. If a COBOL program is found, it is executed.
`arguments`	The arguments to pass to the main function.
`-jar`	Specifies that a program from a JAR file is to be executed.
`jarfile`	The name of the JAR file to be invoked.

Notes:

The Java/COBOL application launcher loads a specified class, and invokes the class's main method, where the method declaration must be in the following format:
```
public static void main(String args[])
```
If the Java application is contained in a JAR file, you need to add it to the classpath by using the -classpath (or -cp) option and specifying the fully qualified class-name.
If you specify a JAR file that contains a manifest including a Main-Class attribute, you can use the -jar option to execute the application.

1.2.5 Multi-threading COBOL Programs

All COBOL programs for use with Java must be linked with the multi-threaded run-time system. To do this, use the -t cob flag. For more information on this flag, see the section Create Multi-threading Program in the chapter Descriptions of cob Flags in your User's Guide. For more information on multi-threading, see your Multi-threaded Programming book.

Calling Procedural COBOL from Java