Micro Focus COBOL Java Class Library

Micro Focus COBOL Runtime Support Library

See:
Description

Packages

com.microfocus.cobol
com.microfocus.cobol.lang
com.microfocus.cobol.lang.internal
com.microfocus.cobol.packagemigration
com.microfocus.cobol.util
mfcobol
mfcobol.lang

Micro Focus COBOL Runtime Support Library

The COBOL RuntimeSystem support classes provides the Java programmer with the ability to integrate COBOL into the Java environment.

What methods are available?

Method	Description
RuntimeSystem.cobcall..	Calls into a COBOL program/entry-point that is enabled for Java/COBOL
RuntimeSystem.cobrcall..	Calls into a COBOL program/entry-point that is not enabled for Java/COBOL
RuntimeSystem.ccall..	Calls into a C function, Strings are NULL terminated.
RuntimeSystem.cobinvoke..	Calls into a Object COBOL method

Java to COBOL DataType Conversion Table

When you send COBOL data to Java, it is converted to an appropriate Java data type. Similarly, when a Java program sends Java data back to COBOL, it is converted to a COBOL data type. The table below defines the conversions which happen when data is passed between Java and COBOL. Some data types are handled differently depending on whether you are using procedural COBOL or the Object COBOL Java domain.

For convenience, copyfile javatypes.cpy defines a set of COBOL data types corresponding to Java data types - you can use these as a shorthand way of declaring data items for use with Java in your COBOL programs. These are shown in the User defined column. You can find javatypes.cpy in your Net Express\source directory or for Server Express $COBDIR/source.

Java Data Type	COBOL Data Type use with .cobcall(...)	COBOL Data Type use with .cobrcall(...)	Object COBOL Data Type use with .cobinvoke(...)	Description
byte	PIC S99 COMP-5	PIC S99 COMP-5	PIC S99 COMP-5	Signed 1-byte integer
short	PIC S9(4) COMP-5	PIC S9(4) COMP-5	PIC S9(4) COMP-5	Signed 2-byte integer
int	PIC S9(9) COMP-5	PIC S9(9) COMP-5	PIC S9(9) COMP-5	Signed 4-byte integer
long	PIC S9(18) COMP-5	PIC S9(18) COMP-5	PIC S9(18) COMP-5	Signed 8-byte integer
boolean	PIC 99 COMP-5	PIC 99 COMP-5	PIC 99 COMP-5	Zero value is false, non-zero is true
char	(Unicode) PIC 9(4) COMP-5	(Unicode) PIC 9(4) COMP-5	(Unicode) PIC 9(4) COMP-5	All characters in Java are represented by 2-byte Unicode characters
float	COMP-13	COMP-13	COMP-13	Floating-point number
double	COMP-23	COMP-23	COMP-23	Double-precision floating-point number
Comp-3 see com.microfocus.cobol.lang.Comp-3	COMP-3	COMP-3	COMP-3	COMP(UTATIONAL)-3 or Packed-Decimal
String	mf-jstring2	POINTER	PIC X(n)	mf-jstring is a user-defined type giving the address, size and capacity of a string or buffer. For a String, the capacity is always zero. You should consider a string passed into a COBOL program as read-only, and not to be amended. For a StringBuffer, the capacity is the total size of the buffer, and the size is the length of the string currently held in the buffer.
StringBuffer
Pointer new Pointer(StringBuffer) new Pointer(String, int capacity)	PIC X(nn)	PIC X(nn)	PIC X(nn)	Wraps a String, StringBuffer so it can safely be passed to COBOL with the right size allocated for the receiving COBOL to modify the Java object. NOTE: StringBuffer capacity is used as the largest possible length that COBOL can edit.
Object	POINTER	POINTER	Object reference	Any Java object. The pointer returned to procedural COBOL can be used with JNI calls
Object[]	POINTER	POINTER	Object reference to instance of class jarray	An array of Java objects. The pointer returned to procedural COBOL can be used with JNI calls
DataType	Structure	Structure	Structure	Complex data structure flattened by Java into a series of bytes.
java.sql.Date CobolDate	mf-jsql-date or 0x jyear pic 9(4). 0x filler pic x. 0x jmonth pic 99. 0x filler pic x. 0x jday pic 99.	mf-jsql-date or 0x jyear pic 9(4). 0x filler pic x. 0x jmonth pic 99. 0x filler pic x. 0x jday pic 99.	mf-jsql-date or 0x jyear pic 9(4). 0x filler pic x. 0x jmonth pic 99. 0x filler pic x. 0x jday pic 99.	Standard SQL Date type as used by JDBC
java.sql.time CobolTime	mf-jsql-time or 0k jhour pic 99. 0x filler pic x. 0x jminute pic 99. 0x filler pic x. 0x jseconds pic 99.	mf-jsql-time or 0k jhour pic 99. 0x filler pic x. 0x jminute pic 99. 0x filler pic x. 0x jseconds pic 99.	mf-jsql-time or 0k jhour pic 99. 0x filler pic x. 0x jminute pic 99. 0x filler pic x. 0x jseconds pic 99.	Standard SQL Time type as used by JDBC
new CobolBigDecimal(java.math.BigDecimal)	pic S9(19)V9(19) comp-3	pic S9(19)V9(19) comp-3	pic S9(19)V9(19) comp-3	The CobolBigDecimal wrapper class is provided to allow COBOL to update the value of a BigDecimal. The constructor for CobolBigDecimal() takes a initial value and the updated value can be obtained by using the .getValue() method.
new CobolBigInteger(java.math.BigInteger)	pic S9(38) comp-3.	pic S9(38) comp-3.	pic S9(38) comp-3.	The CobolBigInteger wrapper class is provided to allow COBOL to update the value of a BigInteger. The constructor for CobolBigInteger() takes a initial value and the updated value can be obtained by using the .getValue() method.
CustomRecord	Structure	Structure	Structure	Complex data structure represented in Java as an array of objects.
CobolNational	pic n(40) usage is national	pic n(40) usage is national	pic n(40) usage is national	The CobolNational class allows PIC N/UTF-16 characters to be passed to COBOL.

NB: New datatypes are highlighted in red.

Java Typedefs (include the copybook javatypes.cpy)

Note: All programs using javatypes.cpy *must* compile with the directive intlevel"4"

Typedef	COBOL Type
jbyte	PIC S99 COMP-5
jshort	PIC S9(4) COMP-5
jint	PIC S9(9) COMP-5
jlong	PIC S9(18) COMP-5
jboolean JNI-TRUE is true JNI-FALSE is false	PIC 99 COMP-5
jchar	PIC 9(4) COMP-5
jfloat	COMP-1
jdouble	COMP-2
jobject	POINTER
jbigdecimal compiler directive intlevel(4) must be set	pic S9(19)V9(19) comp-3
jbiginteger compiler directive intlevel(4) must be set	pic S9(38) comp-3
mf-jsql-date	01 mf-jsql-date is typedef. 03 jyear pic 9(4). 03 filler pic x. 03 jmonth pic 99. 03 filler pic x. 03 jday pic 99.
mf-jsql-time	01 mf-jsql-time is typedef. 03 jhour pic 99. 03 filler pic x. 03 jminute pic 99. 03 filler pic x. 03 jseconds pic 99.

Using ParameterList()

The ParameterList() class in com.microfocus.cobol.lang is designed to aid the coding of parameters being between Java and COBOL.

The general mechanism for using ParameterList is:

   RuntimeSystem.cobcall("myProgram", 

    new ParameterList()

               .add(myOneInt,RuntimeSystem.BY_VALUE)

               .add(mySecondParameter,RuntimeSystem.BY_REFERENCE)

	       .add(10)		// 10 by reference

	       );

Using legacy COBOL in a object oriented way

If a COBOL program is called via the Java method RuntimeSystem.cobcall the COBOL program will always have the same state between invocations. If two Java classes share the same COBOL program then they also share its working-storage too.

      $set intlevel"4" data-context

       working-storage section.

       01 address-rec pic x(30).

       linkage section.

       01 lnk-address-rec pic x(30).

       procedure division.

          goback.

       entry "setAddressBook" using lnk-address-rec.

         move lnk-address-rec to address-rec

         exit program returning 0.

       entry "getAddressBook" using lnk-address-rec.

         move address-rec to lnk-address-rec

         exit program returning 0.

The above program using RuntimeSystem.cobcall would share the same data if used between different Java classes. This makes it difficult to use COBOL from a JavaBean architecture.

If the user created a Java classes that extends from com.microfocus.cobol.CobolBean a instance (data-context) version of cobcall() is made available. For example:

import com.microfocus.cobol.*;

import com.microfocus.cobol.lang.*;



public class MyBean extends com.microfocus.cobol.CobolBean

{

   private StringBuffer address = new StringBuffer(30);



   public MyBean() throws Exception

   {

     super();

     super.cobload("addbook");

   }



   public String getAddress() throws Exception

   {

     Pointer addressPointer = new Pointer(this.address.toString(),30);    

     super.cobcall("getAddressBook", new ParameterList().add(addressPointer));

     this.address.setLength(0);

     this.address.append(addressPointer.toString());

     return address.toString();

   }



   public void setAddress(String address) throws Exception

   {

     super.cobcall("setAddressBook", new ParameterList().add(new Pointer(address,30)));

   }



   public static void main(String[] args) throws Exception

   {

      MyBean bean1 =new MyBean();

      bean1.setAddress("Mr A");



      MyBean bean2 =new MyBean();

      bean2.setAddress("Mr B");



      System.out.println("Bean1.getAddress="+bean1.getAddress());

      System.out.println("Bean2.getAddress="+bean2.getAddress());

   }

}

If the COBOL program shared data, then bean1.getAddress() would be the same as bean2.getAddress(). However because the Java program uses the cobcall() from CobolBean and the COBOL program is compiled with "data-context" not re-entrant/1/2/serial then COBOL working-storage is associated with the bean.

Creating Custom Records using com.microfocus.cobol.lang.CustomRecord interface.

A custom record can be used with .cobcall/.cobrcall mechanism and is designed to make it easier to pass group items into legacy COBOLs.

The CustomRecord interface is:

package com.microfocus.cobol.lang;

public interface CustomRecord

{

  public Object[] getParameters();

  public void setParameters(Object[] parms);

}

In the RecordDemo2 customerDetails is defined as:



  01 customerDetails.

         03 customerName       pic x(30).

         03 customerAddress    pic x(30).

         03 customerRef        pic 9(6).





A Java implementation could be:



import com.microfocus.cobol.lang.*;

import java.text.*;

public class RecordData implements com.microfocus.cobol.lang.CustomRecord

{

    private String customerName;

    private StringBuffer customerAddress;

    private int customerRef;

    RecordData(String name, String address, int ref)

    {

        customerName = name;

        customerAddress = new StringBuffer(address);

        customerRef = ref;

    }

    public String getCustomerName()

    {

      return this.customerName;

    }

    public String getCustomerAddress()

    {

      return this.customerAddress.toString();

    }

    public int getCustomerRef()

    {

      return this.customerRef;

    }

    public Object[] getParameters()

    {

     String strCustomerRef = Integer.toString(this.customerRef);    	

     while(strCustomerRef.length() <  6)

     {

        strCustomerRef = "0"+strCustomerRef;

     }

     customerAddress.setLength(30);        /* must ensure length is right! */

     customerAddress.ensureCapacity(30);

     return new ParameterList()

        .add(new Pointer(this.customerName,30))

        .add(this.customerAddress)

        .add(strCustomerRef.getBytes())

        .getArguments();

    }

    public void setParameters(Object[] parms)

    {

      Pointer ptr = (Pointer)parms[0];

      this.customerName = ptr.toString(); 

      this.customerAddress = (StringBuffer)parms[1];

      byte[] byteCustomerRef = (byte[])parms[2];

      this.customerRef = Integer.parseInt(new String(byteCustomerRef));

    }

    public String toString()

    {

        return "Customer Name    : "+this.customerName+"\n"+

               "Customer Address : "+this.customerAddress+"\n"+

               "Customer Ref     : "+this.customerRef;

    }

}

Migration from mfcobol package to com.microfocus.cobol package

Two migration tools have been provided to allow the user to convert from the mfcobol package to com.microfocus.cobol package.

Using JBuilder migration

JBuilder has a migration tool that works from a property file. Below is a sample property file that can be used with JBuilder to help automate the conversion to the new package structure.

JBuilder property file (filename=to_com_microfocus_cobol.properties)

list.new.7=RuntimeSystem.cobcall_Object

list.new.6=RuntimeSystem

list.new.5=com.microfocus.cobol.RuntimeProperties

list.new.4=com.microfocus.cobol.RuntimeObject

list.new.3=com.microfocus.cobol.Runtime

list.types.1=*.java

list.new.2=CobolException

list.types.0=*.jpr

list.new.1=com.microfocus.cobol.lang.*

list.old.7=RuntimeSystem.cobcall_object

list.old.6=runtime

list.old.5=mfcobol.runtimeProperties

list.old.4=mfcobol.runtimeObject

list.old.3=mfcobol.runtime

list.old.2=COBOLException

list.old.1=mfcobol.lang.*

list.old.0=mfcobol.*

description=
name=mfcobol to com.microfocus.cobol

mfcobol2com Utility

A Java application found in the Java archive called mfcobol.jar provides a simple but effective utility that allows the customer to migrate the source code to the package.

use:
java com.microfocus.cobol.packagemigration.mfcobol2com

1 - User defined datatypes that start with the prefix "j.." are COBOL typedefs for standard COBOL types.

2 - mf-jstring requires the receiving COBOL program use ptr2string pointer to access the Java String/StringBuffer. Using mf-jstring gives the COBOL programmer access to the size and capacity of the Java object.

3 - Parameter can only be passed by reference