Overview (Micro Focus COBOL Java Class Library)
Keywords: Overview, <h1>Micro Focus COBOL Java Class Library</h1>

Overview | Package | Class | Use | Tree | Serialized | Deprecated | Index | Help
PREV NEXT | FRAMES NO FRAMES

#

# 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

Overview | Package | Class | Use | Tree | Serialized | Deprecated | Index | Help
PREV NEXT | FRAMES NO FRAMES

Copyright ? 2000 Micro Focus International Limited. All rights reserved.
This document and the proprietary marks and names used herein are protected by international law.