ILE COBOL Programmer's Guide

COBOL and JNI

Calling a COBOL Program from a Java Program

To call a COBOL program from a Java program, perform the following steps:

Code the COBOL Program

This section describes how to code a COBOL program that is called by a Java program. The guidelines are illustrated in two sample COBOL programs. A later section shows two Java programs that interact with these COBOL programs.

If your COBOL program will be called by a Java program:

  1. Use the PROCESS statement NOMONOPRC (for case-sensitive names) and the option THREAD(SERIALIZE). When the COBOL program is invoked from a Java program, it will run in a Java thread. Specify the NOSTDTRUNC Process option to preserve the content of binary data items.
  2. Identify the COBOL program with a name that consists of:
  3. Copy the predefined interface function table into the program. For a listing of the predefined interface function table, see Member JNI.
  4. To pass a variable from a COBOL program to a Java program, specify the BY VALUE phrase on the CALL. Receive the following arguments, in the following order:
    1. The JNI interface pointer
    2. A reference to the Java class (for a static native method) or to the object (for a nonstatic native method)
    3. Any additional arguments that are required. These arguments correspond to regular Java method arguments.

    Note that COBOL and Java data types are not completely equivalent. See COBOL and Java Data Types.

Figure 61. COBOL Program HELLO


 PROCESS NOMONOPRC NOSTDTRUNC OPTIONS THREAD (SERIALIZE). (1)
 
*** COBOL native program called from Java
*** static method
 
  IDENTIFICATION DIVISION.
  PROGRAM-ID.    "Java_Hello_displayHello".    (2)
  Author.
  INSTALLATION.   IBM Toronto Lab.
  DATE-WRITTEN.
  DATE-COMPILED.
 
  ENVIRONMENT DIVISION.
  CONFIGURATION SECTION.
  SOURCE-COMPUTER.    IBM-ISERIES
  OBJECT-COMPUTER.    IBM-ISERIES
 
  INPUT-OUTPUT SECTION.
  FILE-CONTROL.
 
  DATA DIVISION.
  FILE SECTION.
  WORKING-STORAGE SECTION.
 
  01 IS-COPY     PIC 1.
  01 NAME-PTR            USAGE POINTER.
  01 NAME-LENGTH PIC 9(4) BINARY.
  01 I           PIC 9(4) BINARY.
 
  01 NAME-X.
       05 CHAR-X OCCURS 20 TIMES PIC X.
 
  LINKAGE SECTION.
 
*** JNI interface function table
 
  COPY JNI.     (3)
 
  01 NAME.
       05 CHAR OCCURS 20 TIMES PIC N USAGE NATIONAL.
 
  01 ENV-PTR              USAGE POINTER.
  01 CLASS-REF   PIC S9(9) BINARY.
  01 TITLE-CODE  PIC S9(9) BINARY.
  01 NAME-REF    PIC S9(9) BINARY.
 
  01 INTERFACE-PTR        USAGE POINTER.
 
  PROCEDURE DIVISION USING BY VALUE ENV-PTR     (4a)
                                    CLASS-REF   (4b)
                                    TITLE-CODE  (4c)
                                    NAME-REF.   (4c)
 
 MAIN-LINE SECTION.
 MAIN-PROGRAM-LOGIC.
 
             SET ADDRESS OF INTERFACE-PTR TO ENV-PTR.
             SET ADDRESS OF JNI-NATIVE-INTERFACE TO INTERFACE-PTR.
 
*** Callback JNI interface function GET-STRING-LENGTH to
*** retrieve the name length
 
             CALL GET-STRING-LENGTH USING BY VALUE ENV-PTR     (4)
                                                   NAME-REF
                                    RETURNING INTO NAME-LENGTH.
 
*** Callback JNI interface function GET-STRING-CHARS to
*** retrieve the name characters
 
              CALL GET-STRING-CHARS USING BY VALUE ENV-PTR     (4)
                                                   NAME-REF
                                                   IS-COPY
                                    RETURNING INTO NAME-PTR.
 
             SET ADDRESS OF NAME TO NAME-PTR.
             INITIALIZE NAME-X.
 
             PERFORM VARYING I FROM 1 BY 1 UNTIL (I > NAME-LENGTH)
                   MOVE CHAR(I) TO CHAR-X(I)
             END-PERFORM.
 
             EVALUATE TITLE-CODE
                   WHEN  1
                               DISPLAY "Hello, Mr. ", NAME-X
                   WHEN  2
                               DISPLAY "Hello, Ms. ", NAME-X
                   WHEN OTHER
                               DISPLAY "Hello, ", NAME-X
             END-EVALUATE.
 
             GOBACK.

Figure 62. COBOL Program BYE


  PROCESS NOMONOPRC NOSTDTRUNC OPTIONS THREAD(SERIALIZE).     (1)
 
*** COBOL native program called from Java
*** instance method
 
  IDENTIFICATION DIVISION.
  PROGRAM-ID.    "Java_Bye_displayBye".     (2)
  Author.
  INSTALLATION.   IBM Toronto Lab.
  DATE-WRITTEN.
  DATE-COMPILED.
 
  ENVIRONMENT DIVISION.
  CONFIGURATION SECTION.
  SOURCE-COMPUTER.    IBM-ISERIES
  OBJECT-COMPUTER.    IBM-ISERIES
 
  INPUT-OUTPUT SECTION.
  FILE-CONTROL.
 
  DATA DIVISION.
  FILE SECTION.
 
  WORKING-STORAGE SECTION.
 
  01 IS-COPY     PIC 1.
  01 NAME-PTR            USAGE POINTER.
  01 NAME-LENGTH PIC 9(4) BINARY.
  01 I           PIC 9(4) BINARY.
 
  01 NAME-X.
       05 CHAR-X OCCURS 20 TIMES PIC X.
 
  LINKAGE SECTION.
 
*** JNI interface function table
 
  COPY JNI.     (3)
 
  01 NAME.
       05 CHAR OCCURS 20 TIMES PIC N USAGE NATIONAL.
 
  01 ENV-PTR              USAGE POINTER.
  01 OBJECT-REF  PIC S9(9) BINARY.
  01 TITLE-CODE  PIC S9(9) BINARY.
  01 NAME-REF    PIC S9(9) BINARY.
 
  01 INTERFACE-PTR        USAGE POINTER.
 
  PROCEDURE DIVISION USING BY VALUE ENV-PTR     (4)
                                    OBJECT-REF
                                    TITLE-CODE
                                    NAME-REF.
 
  MAIN-LINE SECTION.
  MAIN-PROGRAM-LOGIC.
 
               SET ADDRESS OF INTERFACE-PTR TO ENV-PTR.
               SET ADDRESS OF JNI-NATIVE-INTERFACE TO INTERFACE-PTR.
 
*** Callback JNI interface function GET-STRING-LENGTH to
*** retrieve the name length
 
               CALL GET-STRING-LENGTH USING BY VALUE ENV-PTR     (4)
                                                     NAME-REF
                                      RETURNING INTO NAME-LENGTH.
 
*** Callback JNI interface function GET-STRING-CHARS to
*** retrieve the name characters
 
              CALL GET-STRING-CHARS USING BY VALUE ENV-PTR     (4)
                                                   NAME-REF
                                                   IS-COPY
                                    RETURNING INTO NAME-PTR.
 
               SET ADDRESS OF NAME TO NAME-PTR.
               INITIALIZE NAME-X.
 
               PERFORM VARYING I FROM 1 BY 1 UNTIL (I > NAME-LENGTH)
                       MOVE CHAR(I) TO CHAR-X(I)
               END-PERFORM.
 
               EVALUATE TITLE-CODE
                      WHEN  1
                                  DISPLAY "Bye, Mr. ", NAME-X
                      WHEN  2
                                  DISPLAY "Bye, Ms. ", NAME-X
                      WHEN  OTHER
                                  DISPLAY "Bye, ", NAME-X
               END-EVALUATE.
 
               GOBACK.

Create the COBOL Module

To create a COBOL module, use the CRTCBLMOD command, as shown in the examples on the two following screens.

+--------------------------------------------------------------------------------+
|                         Create COBOL Module (CRTCBLMOD)                        |
|                                                                                |
| Type choices, press Enter.                                                     |
|                                                                                |
| Module . . . . . . . . . . . . . > BYE           Name, *PGMID                  |
|   Library  . . . . . . . . . . . >   *CURLIB     Name, *CURLIB                 |
| Source file  . . . . . . . . . . > QCBLLESRC     Name                          |
|   Library  . . . . . . . . . . . >   *LIBL       Name, *LIBL, *CURLIB          |
| Source member  . . . . . . . . . > BYE           Name, *MODULE                 |
| Source stream file . . . . . . .                                               |
| Output . . . . . . . . . . . . .   *PRINT        *PRINT, *NONE                 |
| Generation severity level  . . .   30            0-30                          |
| Text 'description' . . . . . . .   *SRCMBRTXT                                  |
|                                                                                |
|                                                                                |
|                            Additional Parameters                               |
|                                                                                |
| Replace module . . . . . . . . . > *YES          *YES, *NO                     |
|                                                                                |
|                                                                                |
|                                                                                |
|                                                                         Bottom |
| F3=Exit   F4=Prompt   F5=Refresh   F10=Additional parameters   F12=Cancel      |
| F13=How to use this display        F24=More keys                               |
+--------------------------------------------------------------------------------+
+--------------------------------------------------------------------------------+
|                         Create COBOL Module (CRTCBLMOD)                        |
|                                                                                |
| Type choices, press Enter.                                                     |
|                                                                                |
| Module . . . . . . . . . . . . . > HELLO         Name, *PGMID                  |
|   Library  . . . . . . . . . . . >   *CURLIB     Name, *CURLIB                 |
| Source file  . . . . . . . . . . > QCBLLESRC     Name                          |
|   Library  . . . . . . . . . . . >   *LIBL       Name, *LIBL, *CURLIB          |
| Source member  . . . . . . . . . > HELLO         Name, *MODULE                 |
| Source stream file . . . . . . .                                               |
| Output . . . . . . . . . . . . .   *PRINT        *PRINT, *NONE                 |
| Generation severity level  . . .   30            0-30                          |
| Text 'description' . . . . . . .   *SRCMBRTXT                                  |
|                                                                                |
|                                                                                |
|                            Additional Parameters                               |
|                                                                                |
| Replace module . . . . . . . . . > *YES          *YES, *NO                     |
|                                                                                |
|                                                                                |
|                                                                                |
|                                                                         Bottom |
| F3=Exit   F4=Prompt   F5=Refresh   F10=Additional parameters   F12=Cancel      |
| F13=How to use this display        F24=More keys                               |
+--------------------------------------------------------------------------------+

Create a Service Program

Bind the module or modules into a service program, using the CRTSRVPGM command as shown below. Specify the EXPORT option.

+--------------------------------------------------------------------------------+
|                       Create Service Program (CRTSRVPGM)                       |
|                                                                                |
| Type choices, press Enter.                                                     |
|                                                                                |
| Service program  . . . . . . . . SRVPGM       > HELLOBYE                       |
|   Library  . . . . . . . . . . .              >   *CURLIB                      |
| Module . . . . . . . . . . . . . MODULE       > HELLO                          |
|   Library  . . . . . . . . . . .              >   *CURLIB                      |
|                           + for more values   > BYE                            |
|                                               >   *CURLIB                      |
| Export . . . . . . . . . . . . . EXPORT       > *ALL                           |
| Export source file . . . . . . . SRCFILE        QSRVSRC                        |
|   Library  . . . . . . . . . . .                  *LIBL                        |
| Export source member . . . . . . SRCMBR         *SRVPGM                        |
| Text 'description' . . . . . . . TEXT           *BLANK                         |
|                                                                                |
|                                                                                |
|                                                                                |
|                                                                                |
|                                                                                |
|                                                                        More... |
| F3=Exit   F4=Prompt   F5=Refresh   F12=Cancel   F13=How to use this display    |
| F24=More keys                                                                  |
+--------------------------------------------------------------------------------+

Code the Java Program

This section describes how to code a Java program that calls a COBOL program. The guidelines are illustrated in two sample Java programs, which call the COBOL programs that were shown in a previous section.

Java source files are stored in the Integrated File System (IFS). You can use the stream file editor, EDTF, to edit these files.

If your Java program will call a COBOL program:

  1. Make a static initializing call to the system method System.loadLibrary to load the COBOL service program that you created in the previous step. (In this example, the service program is named HELLOBYE.)
  2. Declare the COBOL method with the keyword native. For the body of the native method, specify only a semicolon. This indicates that the implementation is omitted.

    You can specify the short name (the name without the argument signature). The JVM will look for a method with this name in the native library; if that fails, the JVM will look for the long name. If you want to overload another native method, use the long name. If a native method has the same name as a Java method, you do not need to specify the long name because the Java method will not exist in the native library.

Figure 63. Java Program Hello.java


 class Hello {
         static {
                 System.loadLibrary("HELLOBYE");     (1)
         }
 
         static native void displayHello(int parm1, String parm2);     (2)
 
         public static void main(String[ ] args) {
               int titleCode;
               String name;
 
               switch (args.length) {
               case 1:
                            titleCode = Integer.parseInt(args[0]);
                            name = "Someone";
                            break;
               case 2:
                            titleCode = Integer.parseInt(args[0]);
                            name = args[1];
                            break;
               default:
                            titleCode = 0;
                            name = "Someone";
                            break;
               }
               displayHello(titleCode, name);
               Bye bye = new Bye( );
               bye.displayBye(titleCode, name);
         }
 }

Figure 64. Java Program Bye.java


 class Bye {
          static {
                  System.loadLibrary("HELLOBYE");     (1)
          }
          static native void displayBye(int parm1, String parm2);     (2)
 }

Compile the Java Program

To compile the Java source programs, you can enter the Qshell interpreter (QSH) and issue the following commands:

javac Hello.java
 
javac Bye.java

Invoke theJava program

To invoke the Java source programs, you can enter the Qshell interpreter (QSH) and issue the following commands:

>java Hello
Hello, Someone
Bye, Someone
>java Hello 1
Hello, Mr. Someone
Bye, Mr. Someone
>java Hello 2 USA
Hello, Ms. USA
Bye, Ms. USA 

You can use the javah tool to generate header files for the Java programs. These header files are used by C and C++ compilers, not by the COBOL compiler, but you might find them useful for checking the naming of native programs.

javah -jni Hello
 
javah -jni Bye


[ Top of Page | Previous Page | Next Page | Table of Contents | Index ]