C$JAVA

Usage

CALL "C$JAVA" 
    USING OP-CODE, CLASS-NAME, METHOD-NAME, METHOD-SIGNATURE,
        FIELD-INT, FIELD-RETURN 
    GIVING STATUS-VAL

Note: To call Java via the C$JAVA routine, HP-UX users must relink the runtime so that it is statically linked to libjvm.sl. To do this, modify lib/Makefile (uncommenting and editing the lines regarding relinking for Java), then run make to relink the runtime.

Parameters

OP-CODE Numeric parameter	Specifies the operation to perform.
CLASS-NAME Alphanumeric data item or literal	Specifies the fully qualified class name, with package name if necessary, of the Java class to load.
METHOD-NAME Alphanumeric data item or literal	Specifies the name of the specific method in the Java class that you want to call.
METHOD-SIGNATURE Alphanumeric data item or literal	Specifies the method signature ID of the exact method to be called. You can get this value by running the Java utility "javap.exe"on the desired jar file or class. This utility comes with the Java JRE and automatically produces the exact signature of a given method. You can copy and paste this signature ID into your CALL "C$JAVA" statement. You can also determine this value manually as described in Method Signatures - ACU.
FIELD-INT Numeric parameter	Specifies the input parameters that the method requires.
FIELD-RETURN Numeric parameter	Specifies the parameter to hold the Java return value from the method.
STATUS-VAL Numeric parameter	Specifies a status value be returned after the call is complete. Possible return values are: CJAVA-SUCCESS VALUE 0. CJAVA-INVALIDARG VALUE -1. CJAVA-INVALIDSIGNATURE VALUE -2. CJAVA-CLASSNOTFOUND VALUE -3. CJAVA-METHODNOTFOUND VALUE -4. CJAVA-INVALIDPARAMTYPE VALUE -5. CJAVA-JAVALIBNOTLOADED VALUE -6. CJAVA-MEMNOTALLOC VALUE -7. CJAVA-INVALIDOPCODE VALUE -8. CJAVA-NOMEMORY VALUE -9. CJAVA-METHODFAILED VALUE -10. CJAVA-MISSINGPARAM VALUE -11. CJAVA-INVALIDINDEX VALUE -12. CJAVA-EXCEPTIONOCCURRED VALUE -13. CJAVA-MISSINGPARAM is returned if a required value is not passed into a Java method. For example, say a method required five parameters, but only four were passed in. CJAVA-INVALIDINDEX is returned if the region specified is not in the array or the region is larger or goes past the end of the array. CJAVA-EXCEPTIONOCCURRED is returned when a Java exception was thrown during the call to C$JAVA. Use the CJAVA-GETEXCEPTIONOBJECT op-code to obtain the object of the Java exception.

Description

In all of the op-codes below, you can pass either the constant name or numeric value shown in parentheses. A java.def file is located in the sample/def directory where you installed ACUCOBOL-GT. It contains the op-codes for C$JAVA, as well as array types and return values. You can include the file java.def in your COBOL program using the following statement if the java.def file is located in the same directory as the .cbl file:

   working-storage section.
   COPY "java.def".

CJAVA-NEW (op-code 1)

Create a new Java object on the local Java Virtual Machine (JVM). You must pass a fully qualified package/classname. Use the GIVING statement to return the object handle. For example:

CALL "C$JAVA" USING CJAVA-NEW, "MyJavaClass", GIVING OBJECT-HANDLE.

CJAVA-DELETE (op-code 2)

Delete an existing Java object.

CJAVA-CREATE (op-code 3)

Create a new Java object. This is the same as using the CJAVA-NEW op-code. See op-code 1 for more details.

CJAVA-DESTROY (op-code 4)

Destroy a Java object. You must pass a valid object handle:

CALL "C$JAVA" USING CJAVA-DESTROY, OBJECT-HANDLE 
   GIVING STATUS-VAL.

See Creating and Using Java Objects in COBOL for more information.

CJAVA-INVOKE (op-code 7)

Same as CJAVA-CALLSTATIC. See op-code 10 for details.

CJAVA-CALL (op-code 8)

Call a virtual Java method. For example:

CALL "C$JAVA" USING CJAVA-CALL, OBJECT-HANDLE, "CobolCallingJavaStringV", "(X)X", FIELD-STRING, FIELD-STRINGRET GIVING STATUS-VAL.

Note that the object handle and method name are passed, but the class name is not required. Because an object handle has already been created, C$JAVA knows what type the handle is.

Methods can be called as static methods, virtual methods, or non-virtual methods by using op-codes 8 -10. If an op-code is not used, the default runtime behavior is to attempt to call the method statically, and then as a virtual method by attempting to create an object using a default constructor. A non-virtual method is called on the specific object that is being used. A virtual method can be called on a method that is inherited from one of the object's superclasses.

CJAVA-CALLNONVIRTUAL (op-code 9)

Call a non-virtual Java method on the specific object that is being used. For example:

CALL "C$JAVA" USING CJAVA-CALLNONVIRTUAL, OBJECT-HANDLE, "CobolCallingJavaStringV", "(X)X", FIELD-STRING, FIELD-STRINGRET GIVING STATUS-VAL.

CJAVA-CALLSTATIC (op-code 10)

Call a static Java method. For example:

CALL "C$JAVA" USING CJAVA-CALLSTATIC, "acuCobolGT/CAcuCobol",
   "CobolCallingJavaDouble", "(D)D", 
   FIELD-DOUBLE, FIELD-DOUBLERET 
   GIVING STATUS-VAL

Note that you can call static methods directly without having to create an object first.

See Calling Methods on Java Objects for additional details.

CJAVA-NEWARRAY (op-code 11)

Create a new Java array. This is the same as using the CJAVA-CREATEARRAY op-code. See op-code 18 for more details. See Creating and Using Java Arrays in COBOL for more information.

CJAVA-DESTROYARRAY (op-code 12)

Destroy a Java array. See Creating and Using Java Arrays in COBOL for more information.

CJAVA-SETARRAYELEMENT (op-code 13)

Set Java array elements. Pass in an array handle, the position in the array to set, and the value to set. In the following example, the first element of an array is set with the first value from an integer table that is USAGE IS SIGNED-INT OCCURS 10.

CALL "C$JAVA" USING CJAVA-SETARRAYELEMENT, ARRAY-HANDLE, 1, INT-TABLE(1), GIVING STATUS-VAL.

Note: Although Java array elements start at 0, COBOL arrays start at "1". Because C$JAVA is a COBOL statement, the SETARRAYELEMENT and GETARRAYELEMENT op-codes, and all array access from C$JAVA, use "1" as the beginning of the array.

CJAVA-GETARRAYELEMENT (op-code 14)

Get a Java array element. This call requires an array handle, the position in the array to get, and the variable into which the array value will be placed. Here is an example:

CALL "C$JAVA" USING CJAVA-GETARRAYELEMENT, 
   ARRAY-HANDLE, 5, INT-TABLE(1), 
   GIVING STATUS-VAL.

In this case, we are getting element 5 from the array and placing it in the first element of an integer table.

See Creating and Using Java Arrays in COBOL for more information.

CJAVA-CLEARARRAY (op-code 15)

Clear a Java array. Pass in the array handle of the array to be cleared. Here is an example:

CALL "C$JAVA" USING CJAVA-CLEARARRAY, ARRAY-HANDLE 
   GIVING STATUS-VAL.

CJAVA-CONVERTARRAYTOTABLE (op-code 16)

Convert a Java array to a COBOL table. Although ACUCOBOL-GT normally does this automatically, this op-code gives the COBOL programmer more precise control over the conversion process. The call takes the array handle, the number of elements to convert, the starting element position in the array, and the COBOL table variable in which to place the converted array.

Here is an example of an array of Java ints being converted to a USAGE SIGNED-INT OCCURS 10 table:

CALL "C$JAVA" USING CJAVA-CONVERTARRAYTOTABLE, 
   ARRAY_HANDLE, 10, 0, INT-TABLE(1) 
   GIVING STATUS-VAL.

CJAVA-LOGMESSAGE (op-code 17)

This operation places an entry in the Java log. Java messages can be logged from a COBOL program using the CJAVA-LOGMESSAGE as follows:

CALL "C$JAVA" USING CJAVA-LOGMESSAGE, "Message to log".

The advantage of using the Java log is that it is thread-safe, and all of the messages from a given thread of execution are written to the same log whether that thread is executing COBOL or Java. Also, logs in Java are highly configurable. Note that the log output above is formatted to report date, time, class, method, and log level before the message. You can configure logging by modifying the logging.properties file found in the runtime directory.

See Using Java Logging from COBOL for additional details.

CJAVA-CREATEARRAY (op-code 18)

Create a new Java array. Following are the array types supported by C$JAVA:

   CJAVA-OBJECTARRAY     VALUE 300.
   CJAVA-BOOLEANARRAY    VALUE 301.
   CJAVA-BYTEARRAY       VALUE 302.
   CJAVA-CHARARRAY       VALUE 303.
   CJAVA-SHORTARRAY      VALUE 304.
   CJAVA-INTARRAY        VALUE 305.
   CJAVA-LONGARRAY       VALUE 306.
   CJAVA-FLOATARRAY      VALUE 307.
   CJAVA-DOUBLEARRAY     VALUE 308.
   CJAVA-STRINGARRAY     VALUE 309.

To create an array of primitive types, pass the type of array, the size of the array, and return the array handle through the GIVING statement. For example:

CALL "C$JAVA" USING CJAVA-CREATEARRAY, 
   CJAVA-INTARRAY, ARRAY-SIZE 
   GIVING ARRAY-HANDLE.

To create an object array:

CALL "C$JAVA" USING CJAVA-CREATEARRAY, 
   CJAVA-OBJECTARRAY, 10 
   GIVING ARRAY-HANDLE.

In this case, the array consists of an array of object handles.

To create a string array:

Even though strings in Java are objects, they are treated separately for the convenience of using them with PIC X tables. Here is an example of creating a string array:

CALL "C$JAVA" USING CJAVA-CREATEARRAY, 
   CJAVA-STRINGARRAY, 10 
   GIVING ARRAY-HANDLE.

See Creating and Using Java Arrays in COBOL for more information.

CJAVA-CONVERTTABLETOARRAY (op-code 19)

Convert a COBOL table to a Java array. Although ACUCOBOL-GT normally does this automatically, this op-code gives the COBOL programmer more precise control over the conversion process. The call requires the COBOL table from which the values will be taken, the number of elements, the position of the first element, and the handle of the destination array.

Here is an example of call that converts a table to an array:

CALL "C$JAVA" USING CJAVA-CONVERTTABLETOARRAY, 
   INT-TABLE(1), 10, 0, ARRAY-HANDLE, 
   GIVING STATUS-VAL.

CJAVA-LOADCLASS (op-code 20)

Manually load a Java class prior to use. Normally, java doesn't require classes to be manually loaded. When you create new object, java typically searches the classpath and loads the class.

CJAVA-DBCONNECT (op-code 21)

Connect to a Java Database Connectivity (JDBC) data source.

Because the CVM.jar package that comes with ACUCOBOL-GT contains a Java class for connecting to JDBC data sources and querying those data sources for ResultSet objects, you do not have to use the C$JAVA routine to do this. However, using C$JAVA is somewhat more efficient because the Connection and ResultSet handles do not have to be created prior to being used.

To use op-codes 21 and 22, you must include the java.def file in the working storage section of your COBOL program. Be sure that java.def file is located in the same directory as the .cbl file.

See Creating and Using a JDBC ResultSet for more information on achieving connectivity with a JDBC data source.

CJAVA-DBQUERY (op-code 22)

Query the JDBC ResultSet. See op-code 21.

CJAVA-NEWREMOTEOBJECT (op-code 23)

Connect to a Remote Object Invocation (RMI) server, and create an instance of a remote object on that server. This operation takes three parameters: the host name, the server name, and the port number. Here is an example of the call:

CALL "C$JAVA" USING CJAVA-NEWREMOTEOBJECT, "localhost", "RemoteInterfaceServer", PORT-NUMBER GIVING REMOTE-OBJ.

CALL "C$JAVA" USING CJAVA-CALL, REMOTE-OBJ, "acuUtilities/RemoteInterfaceServer", "RemoteMethod",   "()X", FIELD-STRINGRET GIVING STATUS-VAL.

CALL "C$JAVA" USING CJAVA-DELETE, REMOTE-OBJ GIVING STATUS-VAL.

CJAVA-STARTREMOTESERVER (op-code 24)

Start the RMI server. For example:

CALL "C$JAVA" USING CJAVA-NEW, "acuUtilities/AcuRMIServer", "()V" GIVING REMOTE-SERVER.
CALL "C$JAVA" USING CJAVA-STARTREMOTESERVER, REMOTE-SERVER, "RemoteInterfaceServer", PORT-NUMBER GIVING STATUS-VAL.

CJAVA-SETARRAYREGION (op-code 25)

Take a Java array object and copy the elements from a COBOL table data item into a specified range.

CJAVA-GETARRAYREGION (op-code 26)

Take a Java array object, get the specified range of elements, and copy them into a COBOL table data item.

CJAVA-GETEXCEPTIONOBJECT (op-code 27)

Return the exception object of the last Java exception thrown. Once the exception object is returned, you can call any of the methods on the exception object that are documented in the Java documentation.

CJAVA-SETSYSTEMPROPERTY (op-code 28)

Change a system property. Useful for setting CLASSPATH and LIBRARYPATH environment variables. For example:

CALL "C$JAVA" USING CJAVA-SETSYSTEMPROPERTY, "java.class.path",
"d:\MyClasses.jar;d:\otherDir" GIVING STATUS-VAL.

CALL "C$JAVA" USING CJAVA-SETSYSTEMPROPERTY, "java.library.path",
"C:\Acucorp\Acucbl700\AcuGT\bin;d:\otherDir" GIVING STATUS-VAL.

CJAVA-CALLJAVAMAIN (op-code 29)

Call a Java main method. For example:

CALL C$JAVA USING CJAVA-CALLJAVAMAIN, CobolCallingJava, \StrParam1, StrParam2, StrParam3, StrParam4 GIVING STATUS-VAL.

This example calls a Java main method with the following signature:

public static void main( String[] args );

The main method signature can include optional exceptions that have been specified by the Java programmer. The first parameter is the op-code, the second parameter is the name of the class containing the main method. This directory or JAR file containing this class must be placed on the CLASSPATH environment variable. The number of string parameters can be zero or as many as is possible to pass using the CALL statement. The COBOL calling Java samples in the sample/java directory have been updated to include a sample of such a call.