Top
NetCOBOL V11.0 J Adapter Class GeneratorUser's Guide
FUJITSU Software

3.2.1 Creating a COBOL Program

The flow of program processing using the adapter class is as follows:

  1. Initialization of the Java VM.

  2. In the case of a multithreaded application, connection of the current thread to the Java VM .

  3. Generation of the object.

  4. Calling the method.

  5. In the case of a multi threaded application, disconnection from the Java VM .

  6. Termination of the Java VM.

Also, be careful when performing the following operations:

3.2.1.1 Initializing the Java VM

To use an adapter class, the Java virtual machine (VM) must first be initialized . Use the JVM-INIT method or the JVM-ATTACH method of the FJ-JAVA-CONTROL class to initialize the Java VM.

A coding sample is shown below:

  ...
REPOSITORY.
    CLASS FJ-JAVA-CONTROL
  ...
PROCEDURE DIVISION.
  ...
    INVOKE FJ-JAVA-CONTROL "JVM-INIT".
  ...

3.2.1.2 Terminating the Java VM

When an adapter class is no longer used, the Java VM must be terminated. Use the JVM-TERMINATE method of the FJ-JAVA-CONTROL class to terminate the Java VM.

A coding sample is shown below:

  ...
REPOSITORY.
    CLASS FJ-JAVA-CONTROL
  ...
PROCEDURE DIVISION.
  ...
    INVOKE FJ-JAVA-CONTROL "JVM-TERMINATE".
  ...

3.2.1.3 Developing a Multithread Application

A multithread application using an adapter class must connect the current thread to the Java virtual machine (VM). When the multithread application is terminated, the current thread must first be disconnected from the Java VM.

Use the JVM-ATTACH method of the FJ-JAVA-CONTROL class to connect the current thread to the Java VM.

To disconnect the current thread from the Java VM, use the JVM-DETACH method of the FJ-JAVA-CONTROL class.

A multithread application sample is shown below:

3.2.1.4 Generating an Object

Generate an object by invoking the adapter class factory method corresponding to the constructor. Generate the factory method with the following name.

Create-JavaClassName-nn  (nn is 01 to 99)

An example of generating a Date class object is shown below:

  ...
REPOSITORY.
    CLASS J-Date AS "java-util-Date"
  ...
WORKING-STORAGE SECTION
01  anDate OBJECT REFERENCE J-Date.
  ...
PROCEDURE DIVISION.
  ...
    INVOKE J-Date "Create-Date-01" RETURNING anDate.
  ...

Note

Since the adapter class name is very long, it is recommended that an alias be assigned by specifying AS in the REPOSITORY paragraph.

3.2.1.5 Invoking a Method

Invoke an instance method by invoking the corresponding adapter class object method. The method name is the same as that of Java. However, if more than one method is defined with the same name, append a numeric suffix to distinguish them (see "5.5.5 Class method" and "5.5.7 Instance Method").

An example of invoking the getTime method of the Date class is shown below:

  ...
REPOSITORY.
    CLASS J-Date AS "java-util-Date"
  ...
WORKING-STORAGE SECTION
01  anDate OBJECT REFERENCE J-Date.
01  currentTime PIC S9(9) COMP-5.
  ...
PROCEDURE DIVISION.
  ...
    INVOKE anDate "getTime" RETURNING currentTime.
  ...

3.2.1.6 Manipulating a Variable

Manipulate a variable through the corresponding adapter class property. The property name is a Java field name with the prefix "JF-". However, if more than one field is defined with the same name, append a numeric suffix to distinguish them.

An example of referencing the class variable AM_PM_FIELD (static field) of the DateFormat class is shown below:

  ...
REPOSITORY.
    CLASS J-DateFormat AS "java-text-DateFormat"
  ...
WORKING-STORAGE SECTION
01  FMT-Type PIC S9(9) COMP-5.
  ...
PROCEDURE DIVISION.
  ...
    MOVE JF-AM_PM_FIELD OF J-DateFormat TO FMT-Type.
  ...

3.2.1.7 Comparing Object References

COBOL uses "=" to check whether multiple object references point to the same object. To check whether the Java objects pointed to by the adapter objects are the same, COBOL uses the J-EQUALS method of the adapter class instead of "=". The adapter class always has the J-EQUALS method.

An example of comparing two Date objects is shown below. The condition is met when Date-1 and Date-2 point to the same Java object.

  ...
REPOSITORY.
    CLASS J-Date AS "java-util-Date"
  ...
WORKING-STORAGE SECTION
01  Date-1 OBJECT REFERENCE J-Date.
01  Date-2 OBJECT REFERENCE J-Date.
01  rst    PIC 1.
  ...
PROCEDURE DIVISION.
  ...
    INVOKE Date-1 "J-EQUALS" USING CONTENT Date-2 RETURNING rst.
    IF rst = B"1" THEN
        Condition met
  ...

3.2.1.8 Assignment to a Subclass

COBOL uses AS to assign an object to a subclass. However, it uses the J-NARROW method instead of AS to assign an adapter object. The adapter class always has the J-NARROW method.

An example of assigning an object, which has been referenced with Object class data, into Data class data is shown below:

  ...
REPOSITORY.
    CLASS J-Object AS "java-lang-Object"
    CLASS J-Date AS "java-util-Date"
  ...
WORKING-STORAGE SECTION
01  anDate OBJECT REFERENCE J-Date.
01  anObject OBJECT REFERENCE J-Object.
  ...
PROCEDURE DIVISION.
  ...
    INVOKE J-Date "J-NARROW" USING CONTENT anObject RETURNING anDate.
  ...

3.2.1.9 Mapping java.lang.String into PIC X

The java.lang.String is mapped into the java-lang-String class in the generation of the normal adapter class. In this case, creation of the user's application becomes somewhat complicated because conversion between the String object and the COBOL data items must be performed using the java-lang-String class method (such as NEW-STRING-X, GET-STRING-X).

When the adapter class is generated by specifying the -s option or by specifying the "Option String" parameter, the following items can be handled as alphanumeric items in the user's applications, since the java.lang.String type is mapped into PIC X ANY LENGTH:

Example

When the -s option and "Option String" parameter are not specified, the conversion between the String object and the COBOL data items must be performed in the user's application using the java-lang-String class method (such as NEW-STRING-X and GET-STRING-X).

  :
REPOSITORY.
    CLASS J-Date AS "java-util-Date"
    CLASS J-String AS "java-lang-String"
    CLASS J-DateFormat AS "java-text-DateFormat"
  :
WORKING-STORAGE SECTION
01  aDateFormat  OBJECT REFERENCE J-DateFormat.
01  aDate        OBJECT REFERENCE J-Date.
01  dateString   OBJECT REFERENCE J-String.
01  dateValue    PIC X(30).
  :
PROCEDURE DIVISION.
  :
    MOVE "2000/01/01" & X"00" TO dateValue.
    INVOKE J-String "NEW-STRING-X" USING dateValue RETURNING dateString.
    INVOKE aDateFormat "parse" USING dateString RETURNING aDate.
    :
    INVOKE aDate "toString" RETURNING dateString.
    INVOKE dateString "GET-STRING-X" RETURNING dateValue.
  :

When the -s option or the "Option String" parameter is specified, the conversion between the String object and the COBOL data items is not necessary since an alphanumeric item can be specified as the String type argument and returns a value directly.

  :
REPOSITORY.
    CLASS J-Date AS "java-util-Date"
    CLASS J-DateFormat AS "java-text-DateFormat"
  :
WORKING-STORAGE SECTION
01  aDateFormat  OBJECT REFERENCE J-DateFormat.
01  aDate        OBJECT REFERENCE J-Date.
01  dateValue    PIC X(30).
  :
PROCEDURE DIVISION.
  :
    MOVE "2000/01/01" & X"00" TO dateValue.
    INVOKE aDateFormat "parse" USING dateValue RETURNING aDate.
    :
    INVOKE aDate "toString" RETURNING dateValue.
  :

Note

  • The return value of the java.lang.String class constructor is the java.lang.String class

  • When the String object method is used, the creation of the object (calling the String constructor or calling the NEW-STRING-X method) is necessary.

  • To refer/set the java.lang.String type field (class variable or instance variable), specify its size using -s option or "Option String" parameter.

  • When you want to handle the String type NULL object, do not use the -s option and "Option String" parameter.

3.2.1.10 Using national data (Unicode)

NetCOBOL processes Unicode data using national data item definitions encoded in UTF-16. UTF-16 data can be stored in either big-endian or little-endian format.

Big-endian

"AB12" --> X"0041 0042 0031 0032"

Little-endian

"AB12" --> X"4100 4200 3100 3200"

NetCOBOL of this system is little-endian by default. To change encoding to big-endian use compiler option ENCODE(UTF8,UTF16,BE). For details, refer to the "NetCOBOL User's Guide".

The generated java adapter class encoding much match the encoding of the program. If the program is UTF-16 little-endian, the adapter class must be UTF-16 little-endian. If the program is UTF-16 big-endian, the adapter class must be UTF-16 big-endian.

Note

The adapter class cannot process the Unicode data whose national class is UTF-32.

3.2.1.11 End Control of Character String

When passing a character string that is shorter than the data item length to an ordinary adapter class, the end of string (X"00") must be set. The following example shows that "ABC" is copied to alphanumeric item initialValue having length of 50 characters and is passed to the NEW-STRING-X method:

    :
REPOSITORY.
    CLASS J-String AS "java-lang-String"
    :
WORKING-STORAGE SECTION.
01  initialValue  PIC X(50).
01  aString       OBJECT REFERENCE J-String.
    :
PROCEDURE DIVISION.
    :
    MOVE "ABC" & X"00" TO initialValue.
    INVOKE J-String "NEW-STRING-X" USING initialValue RETURNING aString.

If an adapter class is generated by specifying the -t option or the "Option Terminal" parameter, the character string that is shorter than the data item length can be passed to a method without setting the end of string, since the end (X "00") of the character string is set in the adapter class.

The following example shows that "ABC" is copied to alphanumeric item initialValue having the length of 50 characters and is passed to the NEW-STRING-X method:

    :
REPOSITORY.
    CLASS J-String AS "java-lang-String"
    :
WORKING-STORAGE SECTION.
01  initialValue  PIC X(50).
01  aString       OBJECT REFERENCE J-String.
    :
PROCEDURE DIVISION.
    :
    MOVE "ABC" TO initialValue.
    INVOKE J-String "NEW-STRING-X" USING initialValue RETURNING aString.

3.2.1.12 Exception Processing

When an adapter class detects an error during processing, the exception object is generated. FJ-JAVA-ERROR class is the class of the exception object.

In order to detect an exception generated in the adapter class, using the "exception object", the "exception handling" needs be described in the declaratives of the procedure division of the program, using the USE statement. When the method of the FJ-JAVA-ERROR class is used in the exception handling, the exception message, exception type and Java exception information can be extracted. For the details of the exception handling using the USE statement, refer to "Defining Exception Processes" of the "NetCOBOL User's Guide".

Example of coding of the exception handling is shown as follows:

  :
REPOSITORY.
    CLASS FJ-JAVA-ERROR
  :
WORKING-STORAGE SECTION
01 errMessage     PIC X(256).
01 expMessage     PIC X(1024).
01 expClass       PIC X(256).
01 errCode        PIC S9(9) COMP-5.
01 errMessageLen  PIC S9(9) COMP-5.
01 expMessageLen  PIC S9(9) COMP-5.
01 expClassLen    PIC S9(9) COMP-5.
01 rc             PIC S9(9) COMP-5.
  :
PROCEDURE DIVISION.
DECLARATIVES.
ERR SECTION.
  USE AFTER EXCEPTION FJ-JAVA-ERROR.
  INVOKE EXCEPTION-OBJECT "GET-CODE" RETURNING errCode.
  INVOKE EXCEPTION-OBJECT "GET-MESSAGE"
         USING errMessage RETURNING errMessageLen.
  INVOKE EXCEPTION-OBJECT "GET-EXCEPTION"
         USING expMessage expMessageLen expClass expClassLen
         RETURNING rc.
  DISPLAY "Error Code:    " errCode.
  DISPLAY "Error Message: " errMessage(1:errMessageLen).
  IF rc NOT = -1 THEN
    DISPLAY "Java Class Name:        " expClass(1:expClassLen)
    DISPLAY "Java Exception Message: " expMessage(1:expMessageLen)
  END-IF.
END DECLARATIVES.
  :

Note

When the exception handling is not described in a program, the program runtime error (JMP0104I-U) occurs due to the occurrence of the exception object.