Messages, return codes, and abnormal termination

The JZOS batch launcher completes under one of the following circumstances:
  • The Java™ main() method that the launcher ran returns, and all the non-daemon Java threads completed.
  • A System.exit(rc) message is issued directly by the application, or in response to a MVS console STOP(P) command.
  • The Java main() thread ends due to an uncaught exception.
  • An error occurs in the launcher.
  • An ABEND occurs in the launcher or Java VM. For information about ABENDs in the VM, see Problem determination in the SDK user guide.

When the batch launcher completes normally, it emits a return code.

If the batch launcher ends due to an uncaught exception in the Java main method, the SYSOUT output contains this message:
JVMJZBL1047W JZOS batch launcher completed with Java exception, return code=100
If the launcher itself fails, the SYSOUT output contains this message:
JVMJZBL1042E JZOS batch launcher failed, return code=nnn
Where nnn is one of the codes that are described in the following table.
If the launcher completes without an internal error, the return code that the Java application sets by using the System.exit(rc) method is returned and the SYSOUT output contains this message:
JVMJZBL1021N JZOS batch launcher completed, return code=0

To prevent a Java exit code from matching a JZOS exit code, avoid the range 100 - 102.

Table 1.
Return code Name Notes
0 RC_OK The Java main() method that the launcher ran returned normally, or a System.exit() or System.exit(0) message was used to shut down the JVM.
100 RC_MAIN_EXCEPTION The Java main class was not found or the main() method threw an exception.
101 RC_CONFIG_ERR A configuration or setup error occurred. Check SYSOUT messages for more diagnostic information.
102 RC_SYSTEM_ERR A system or internal error occurred. Check SYSOUT messages for more diagnostic information.

You can use the JZOS_ABEND_EXIT optional environment variable to force the batch launcher to ABEND under certain error conditions. Specify JZOS_ABEND_EXIT=n where n is a positive integer in the range 0-99. Other values are ignored.

If this environment variable is not set, the current functionality does not change.

If this environment variable is set and the exit code from the Java application is either negative or greater than the value of this environment variable, the JZOS batch launcher ends with ABEND U3333-rc, where rc is the nonzero exit or condition code that would normally be used to end the job step.

Note: The rc value is an unsigned hexadecimal value 0-4095, whereas the exit code from Java is a signed int. This value is mapped by using the normal system conventions. The rc value is the unsigned representation of the lower order 12 bits of the exit code.

The ABEND is issued with an option to suppress Language Environment® and system dumps. For more information, see clean-up option 3 in CEE3AB2—Terminate enclave with an abend and reason code.

The following example sets the environment variable JZOS_ABEND_EXIT=99:
// EXEC PROC=JVMPRCxx,JAVACLS='com.package.MyClass',
//CEEOPTS DD * ENVAR("JZOS_ABEND_EXIT=99")
//STDENV *
...
//
Note:
  1. In this example, any System.exit(n) value in the range 0-99 results in normal step completion with CC=0-99. An exit code of 100 or greater, such as uncaught exceptions or the use of the System.exit(1000) method, results in an ABEND.
  2. Specify the environment variable in Language Environment options to the JZOS batch launcher as in the previous example, rather than in the STDENV script, in case a failure occurs when the script is processed.