Configuring environment variables for JZOS

The batch launcher requires the //STDENV file to contain a shell script that is used to set the environment variables that are used to configure the Java™ runtime environment. This file is used as input to the UNIX System Services shell (/bin/sh) and has the following requirements:

  • The script must export the environment variables to set by using the export shell command.
  • The input must not contain line numbers.
  • The script must not issue the exit shell command.
  • The script must be run under a regular shell not a 'login' shell, so that the /etc/profile script and user .profile script are not automatically run. These scripts can be explicitly run ('dotted in') if they are needed.

For an example STDENV DD, see Sample JCL file.

To use private program libraries with your JZOS Batch Launcher application, you must specify either a JOBLIB DD statement or a STEPLIB DD statement. Exporting the STEPLIB environment variable by using the export shell command has no effect.

For example:


//JVMPRC21 PROC JAVACLS=, < Fully Qualified Java class..RQD
// ARGS=, < Args to Java class
// LIBRARY=’<HLQ>.JZOS.LOADLIB’, < STEPLIB FOR JVMLDM module ...
//JAVAJVM EXEC PGM=JVMLDM&VERSION;,REGION=&REGSIZ;,
// PARM=’&LEPARM/&LOGLVL;&JAVALS; &ARGS;’
// STEPLIB DD DSN=&LIBRARY,DISP=SHR
// DD DSN=<HLQ>.<DATASET>,DISP=SHR
...
This example defines a STEPLIB DD <HLQ>.JZOS.LOADLIB statement for locating the JZOS batch launcher and a STEPLIB DD <HLQ>.<DATASET> statement for locating other programs that might be run.

The following tables show the environment variables that are required or are commonly used with the Java batch launcher. Your Java application, or libraries that it uses, might require other environment variables.

Customizing a reusable configuration script

It's often a good idea to create a shell script that handles most, if not all, of the environment variable configuration for your installation's batch Java jobs. The sample shell script jzos_config.sh (included in the downloadable JZOS samples package) can be customized to meet your installation requirements.The following example assumes that you customized this script and placed it in the /etc directory:
//jobname JOB ...


//stepname EXEC PROC=JVMPRC21,
//JAVACLS=’com.ibm.jzos.sample.HelloWorld’
//STDENV DD *
APP_HOME=/usr/local/apps/myapp
. /etc/jzos_config.sh
//

Setting the batch launcher working directory

To set the working directory of your Java application, include a cd command for that directory in the STDENV file. If this file contains multiple cd commands, the directory that the last cd command references is used as the working directory.
//jobname JOB ...


//stepname EXEC PROC=JVMPRC21,
//JAVACLS=’com.ibm.jzos.sample.HelloWorld’
//STDENV DD *
cd /tmp


export JAVA_HOME=/usr/lpp/java/J21.0_64 export PATH=/bin:"${JAVA_HOME}"/bin////

System environment variables

For more information, see the z/OS® UNIX System Services Planning guide.
Table 1. System environment variables
Environment variable Description
PATH A colon-separated list of directories that is used to search for runnable files. Must include at least /bin and $JAVA_HOME/bin.
JAVA_HOME Should point to the base Java SDK directory.
LIBPATH A colon-separated list of directories that is used to search for dynamic shared libraries. Must include at least /lib, /usr/lib, $JAVA_HOME/bin, $JAVA_HOME/lib, and $JAVA_HOME/lib/j9vm.
LANG Specifies the language that system messages are displayed in. The system default is C.
TZ The time zone name. This variable must be set for Java applications to display local times.
NLSPATH A colon-separated list of directories that the system searches for message catalogs.

Java SDK environment variables

For more information, see Environment variables in the OpenJ9 user documentation.
Table 2. Java SDK environment variables
Environment variable Description
CLASSPATH A colon-separated list of directories and .jar names that are used to search for Java classes.
OPENJ9_JAVA_OPTIONS This variable is used to set Java SDK options. These options can include -X options, -D system property options, or standard options; for example, -Xms256m -Djava.compiler=NONE -verbose:gc

For more information, see Java SDK options and system properties. See the entry for JZOS_JVM_OPTIONS in the following section for limitations.

JZOS environment variables

Table 3. JZOS environment variables
Environment variable Description
JZOS_ENABLE_MVS_COMMANDS = {true | false} This environment variable determines whether JZOS allows processing of the MVS operator commands START (S), MODIFY (F), and STOP (P). If set to false, the JZOS batch launcher does not respond to MVS operator commands. The default if not specified is true. For more information, see MVS console interface.
JZOS_OUTPUT_ENCODING = {codepage} This environment variable specifies the code page that JZOS uses for its output to STDOUT and STDERR. If not specified, the default code page for the current locale is used. If LANG=C is set, this default is normally UTF-8. For more information, see Controlling output encoding.
JZOS_ENABLE_OUTPUT_TRANSCODING = {true | false} If set to false, raw bytes that are written to the System.out and System.err streams are not transcoded to the JZOS_OUTPUT_ENCODING code page. For more information, see Controlling output encoding.
JZOS_GENERATE_SYSTEM_EXIT = {true | false } If set to true, JZOS generates a System.exit() call upon completion of the main() method. This call causes JZOS to complete, even if active non-daemon threads exist. The default if not specified is false, which means that JZOS waits for non-daemon threads to complete before it exits.
JZOS_MAIN_ARGS = {classname and arguments}
JZOS_MAIN_ARGS_DD = {ddname | MAINARGS }
Use these variables to specify extra arguments to the main method that JZOS runs. For more information, see Specifying the Java main class and its arguments.
JZOS_JVM_OPTIONS The Java VM does not recognize some Java SDK options and system properties when you specify them in the OPENJ9_JAVA_OPTIONS environment variable. Instead, use the JZOS_JVM_OPTIONS environment variable to specify these options. The default property settings must be specified along with the desired extensions when you use the JZOS_JVM_OPTIONS variable.
JZOS_ABEND_EXIT = n

Where n is a positive integer in the range 0-99.

If this environment variable is set and the JZOS Batch Launcher has a nonzero exit or condition code that is greater than the value that is specified in JZOS_ABEND_EXIT variable, then the JZOS Batch Launcher forces an abnormal termination with a user ABEND. For more information, see Messages, return codes, and abnormal termination.
HJV_JZOS_JVM_SMF_LOGGING = { true | false } If set to true, the JZOS batch launcher registers a Java VM shutdown hook to log an SMF record that contains Java runtime performance statistics just before the JVM shuts down. The use of this environment variable is preferred over the JZOS_JVM_SMF_LOGGING variable, which is deprecated and will be eventually removed in the next version of Java. For more information about the format of the SMF record, see Java runtime statistics. The default if not specified is false.
HJV_JZOS_JVM_SMF_LOGGING_INTERVAL = n

Where n is a positive integer in the range 1-Long.MAX_VALUE.

This environment variable takes effect only if the HJV_JZOS_JVM_SMF_LOGGING variable is set to true. This environment variable enables the JZOS batch launcher to schedule a periodic task where a single SMF record that contains Java runtime performance statistics is logged every n seconds. If n is outside the supported range of values or if this environment variable is not set, periodic logging of SMF records is disabled. For more information about the format of the SMF record, see Java runtime statistics.
HJV_JZOS_JVM_SMF_THREADS = { true | false } This environment variable takes effect only if the HJV_JZOS_JVM_SMF_LOGGING variable is set to true. This environment variable controls whether individual per thread detail is included in the SMF record. If this environment variable is not set, is set to false, or is set to any value other than true, individual per thread detail is omitted from the SMF record. For more information about the format of the SMF record, see Java runtime statistics.
HJV_JZOS_JVM_SMF_THREADS_NATIVE_ID = { true | false } This environment variable takes effect only if both the HJV_JZOS_JVM_SMF_LOGGING and HJV_JZOS_JVM_SMF_THREADS variables are set to true. If this environment variable is set to true, the native operating system thread ID field in the individual per thread detail section of the SMF record is assigned the native operating system thread ID of the corresponding Java thread. If this environment variable is not set, set to false, or any value other than true, then a value of -1 is assigned. For more information about the format of the SMF record, see Java runtime statistics.