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.
The script must consist of valid Unix shell script lines. Take care to avoid saving line numbers in the script because they are not valid Unix shell syntax and cause the affected lines to fail.
Errors in the //STDENV shell script syntax might cause the JZOS batch launcher to hang indefinitely without an error indication. Running the //STDENV shell script as a stand-alone z/OS UNIX System Services shell script helps to identify syntax errors that caused the launcher to hang.
JZOS does some checking to make sure that the script is properly formatted. However, it might not detect all the potential syntax errors in the script.

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:




//JVMPRC25 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 the 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=JVMPRC25,
//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 script that contains the STDENV DD statement. If this script contains multiple cd commands, the directory that the last cd command references is used as the working directory.

//jobname JOB ...



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



export JAVA_HOME=/usr/lpp/java/J25.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_STRICT_JCL_CONFIG = {true \| false}`	This environment variable determines the behavior of JZOS during its initial environment set up. If set to true, the job is terminated if any error occurs during the environment set up. If set to false or not configured, the job is not terminated. The default is false, which is the same as not configured.
`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 usually `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 required 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.