IGY-JAVAIOP-CALL-EXCEPTION

The IGY-JAVAIOP-CALL-EXCEPTION special register provides access to the Java™ exception object produced when an exception is encountered during a call from COBOL to a static Java method using the CALL statement.

When a call to a static Java method is issued from a COBOL program using a CALL statement with a literal target of the form 'Java.java-class-name.java-static-method-name' and a Java exception occurs during the call, the IGY-JAVAIOP-CALL-EXCEPTION special register can be accessed from COBOL statements specified in the ON EXCEPTION phrase of the CALL statement to refer to the Java exception object of the associated Java exception. Having access to the object reference for this Java exception object allows user exception handling code in COBOL to use JNI functions to perform various tasks during exception handling, such as re-throwing the exception. However, it is not necessary to reference this special register in such exception handling code. Knowing that an exception occurred and performing the appropriate COBOL error handling is often sufficient for an interoperable application.

Notes:

When an exception occurs in a call to a static Java method using the CALL statement, the exception is cleared before the code specified in the ON EXECEPTION phrase is run. To propagate the exception up the chain of callers so that other callers can provide caller-specific handling for the exception, it is possible to re-throw the exception using the JNI Throw() function.
Whenever a COBOL program makes calls to JNI functions, the program should either be compiled with the DLL option in effect, or the JNI calls must be under the scope of a CALLINTERFACE DLL directive. It is not necessary to link the program as a DLL, however. Furthermore, at runtime it is necessary to include the directory containing the DLL file libjvm.dll in your LIBPATH environment variable. When the JAVAIOP(...,JAVA64,...) option is in effect, the directory containing the libjvm31.dll must be added to the front of your LIBPATH.
Finally, you will need to link your application with side deck file igzcjni2.x (for pure AMODE 31 applications), igzxjni2.x (for mixed AMODE 31 COBOL with AMODE 64 Java applications), or igzqjni2.x (for pure AMODE 64 applications). These side deck files reside in the lib subdirectory of the COBOL install directory in the z/OS UNIX file system. The side deck files can also be found as members in the relevant SCEELIB run time data set.

See the following example:


  DATA DIVISION.
  LINKAGE SECTION.
  COPY JNI SUPPRESS.
  :
  PROCEDURE DIVISION.
  :
      set address of JNIEnv to JNIEnvPtr
      set address of JNINativeInterface to JNIEnv
      : 
      CALL 'Java.com.acme.MyClass.myMethod' USING ...
        ON EXCEPTION
          <user-error-handling-code>
          *> re-throw exception
          >>CALLINTERFACE DLL
          CALL THROW USING BY VALUE JNIEnvPtr
                                    IGY-JAVAIOP-CALL-EXCEPTION
          GOBACK
      END-CALL

When the LP(32) compiler option is in effect, IGY-JAVAIOP-CALL-EXCEPTION has the implict definition:

01 IGY-JAVAIOP-CALL-EXCEPTION PIC 9(9) USAGE COMP-5 VALUE 0.

When the LP(64) compiler option is in effect or the JAVAIOP(...,JAVA64,...) compiler option is in effect, IGY-JAVAIOP-CALL-EXCEPTION has the implicit definition:

01 IGY-JAVAIOP-CALL-EXCEPTION PIC 9(18) USAGE COMP-5 VALUE 0.

The value of IGY-JAVAIOP-CALL-EXCEPTION is reset to 0 at the beginning of every program invocation.