JVM server options

Applicability of options to different uses of JVM server

Different options are applicable, depending on how the JVM server is being used. The following table indicates whether an option is mandatory, supported but optional, or not supported for a particular use of a JVM server.

Table 1. Options by JVM server use

Option	OSGi	Liberty	Axis2	STS
CLASSPATH_PREFIX	Not supported	Not supported	Supported	Supported
CLASSPATH_SUFFIX	Not supported	Not supported	Supported	Supported
DISPLAY_JAVA_VERSION	Supported	Supported	Supported	Supported
JAVA_DUMP_TDUMP_PATTERN	Supported	Supported	Supported	Supported
JAVA_HOME	Mandatory	Mandatory	Mandatory	Mandatory
JAVA_PIPELINE	Not supported	Not supported	Mandatory	Not supported
JNDI_REGISTRATION	Supported	Not supported	Supported	Supported
JVMTRACE	Supported	Supported	Supported	Supported
LIBPATH_PREFIX	Supported - use only under the guidance of IBM® service personnel	Supported - use only under the guidance of IBM service personnel	Supported - use only under the guidance of IBM service personnel	Supported - use only under the guidance of IBM service personnel
LIBPATH_SUFFIX	Supported	Supported	Supported	Supported
OSGI_BUNDLES	Supported	Not supported	Not supported	Not supported
OSGI_CONSOLE	Supported	Not supported	Not supported	Not supported
OSGI_FRAMEWORK_TIMEOUT	Supported	Supported	Not supported	Not supported
PRINT_JVM_OPTIONS	Supported	Supported	Supported	Supported
SECURITY_TOKEN_SERVICE	Not supported	Not supported	Not supported	Mandatory
STDERR	Supported	Supported	Supported	Supported
STDIN	Supported	Supported	Supported	Supported
STDOUT	Supported	Supported	Supported	Supported
USEROUTPUTCLASS	Supported	Not supported	Supported	Supported
WLP_INSTALL_DIR	Not supported	Mandatory	Not supported	Not supported
WLP_OUTPUT_DIR	Not supported	Supported	Not supported	Not supported
WLP_USER_DIR	Not supported	Supported	Not supported	Not supported
WLP_ZOS_PLATFORM	Not supported	Supported	Not supported	Not supported
WORK_DIR	Supported	Supported	Supported	Supported
WSDL_VALIDATOR	Supported	Not supported	Supported	Supported
ZCEE_INSTALL_DIR	Not supported	Optional	Not supported	Not supported

Descriptions of options

CLASSPATH_PREFIX, CLASSPATH_SUFFIX=class_pathnames

Use these options to specify directory paths, Java™ archive files, and compressed files to be searched by a JVM that is not OSGi enabled (for example, it is used for Java web services). Do not set a class path if you want to use an OSGi framework because the OSGi framework handles the class loading for you. If you use these options to specify the standard class path for Axis2, you must also specify JAVA_PIPELINE=TRUE to start the Axis2 engine.

CLASSPATH_PREFIX adds class path entries to the beginning of the standard class path, and CLASSPATH_SUFFIX adds them to the end of the standard class path. You can specify entries on separate lines by using a \ (backslash) at the end of each line that is to be continued.

Use the CLASSPATH_PREFIX option with care. Classes in CLASSPATH_PREFIX take precedence over classes of the same name that are supplied by CICS and the Java run time and the wrong classes might be loaded.

CICS builds a base class path for a JVM by using the /lib subdirectories of the directories that are specified by the USSHOME system initialization parameter and the JAVA_HOME option in the JVM profile. This base class path contains the Java archive files that are supplied by CICS and by the JVM. It is not visible in the JVM profile. You do not specify these files again in the class paths in the JVM profile.

Use a colon, not a comma, to separate multiple items that you specify by using the CLASSPATH_PREFIX or CLASSPATH_SUFFIX options.

JAVA_DUMP_TDUMP_PATTERN=

A z/OS® UNIX System Services environment variable that specifies the file name to be used for transaction dumps (TDUMPs) from the JVM. Java TDUMPs are written to a data set destination in the event of a JVM abend.

DISPLAY_JAVA_VERSION={TRUE|FALSE}

If this option is set to TRUE, whenever a JVM is started by an application CICS writes message DFHSJ0901 to the MSGUSER log, showing the version and build of the IBM Software Developer Kit for z/OS, Java Technology Edition that is in use.

JAVA_HOME=/usr/lpp/java/javadir/

Specifies the installation location for IBM 64-bit SDK for z/OS, Java Technology Edition in z/OS UNIX. This location contains subdirectories and Java archive files that are required for Java support.

The supplied sample JVM profiles contain a path that was generated by the JAVADIR parameter in the DFHISTAR CICS installation job. The default for the JAVADIR parameter is java/J7.0_64/, which is the default installation location for the IBM 64-bit SDK for z/OS, Java Technology Edition. This value produces a JAVA_HOME setting in the JVM profiles of /usr/lpp/java/J7.0_64/.

JAVA_PIPELINE={TRUE|FALSE}

Adds the required Java archive files to the class path so that a JVM server can support web services processing in Java standard SOAP pipelines. The default value is FALSE. If you set this value, the JVM server is configured to support Axis2 instead of OSGi. You can add more JAR files to the class path by using the CLASSPATH options.

Note: The options JAVA_PIPELINE=TRUE and SECURITY_TOKEN_SERVICE=TRUE are not compatible.

JNDI_REGISTRATION={TRUE|FALSE}

Specifies that the JNDI registration JAR files are automatically added to the JVM runtime environment to support the usage of the JNDI by Java applications. This option is ignored for Liberty JVM servers. It is possible to opt out of the automatic addition of these files by setting JNDI_REGISTRATION=FALSE. If this function is not required, opting out can prevent potential clashes with newer JAR files, can keep the JVM footprint smaller, and avoids unnecessary class loading.

JVMTRACE={&APPLID;.&JVMSERVER;.Dyyyymmdd.Thhmmss.dfhjvmtrc|file_name}

Specifies the name of the z/OS UNIX file to which Java tracing is written during the startup and termination of a JVM server. You can specify an absolute or relative filename for JVMTRACE. If you specify a relative filename the trace file will be created in the directory specified by the WORK_DIR option. If the file already exists, output is appended to the end of the file. If you specify an absolute filename then you must make sure that all the relevant directories are created on z/OS UNIX, and that the CICS regions are given read, write, and execute access to them. If you do not set a value for this option, CICS automatically creates unique trace files for each JVM server. CICS uses the &APPLID; and &JVMSERVER; symbols, and the date and time stamp when the JVM server started. This file is created in the directory that is specified by the WORK_DIR option.

LIBPATH_PREFIX, LIBPATH_SUFFIX=pathnames

Specifies directory paths to be searched for native C dynamic link library (DLL) files that are used by the JVM, and that have the extension .so in z/OS UNIX. This includes files that are required to run the JVM and additional native libraries that are loaded by application code or services.

The base library path for the JVM is built automatically by using the directories that are specified by the USSHOME system initialization parameter and the JAVA_HOME option in the JVM profile. The base library path is not visible in the JVM profile. It includes all the DLL files that are required to run the JVM and the native libraries that are used by CICS.

You can extend the library path by using the LIBPATH_SUFFIX option. This option adds directories to the end of the library path, after the base library path. Use this option to specify directories that contain any additional native libraries that are used by your applications. Also, use this option to specify directories that are used by any services that are not included in the standard JVM setup for CICS. For example, the additional native libraries might include the DLL files that are required to use the DB2® JDBC drivers.

The LIBPATH_PREFIX option adds directories to the beginning of the library path, before the base library path. Use this option with care; if DLL files in the specified directories have the same name as DLL files on the base library path, they are loaded instead of the supplied files.

Use a colon, not a comma, to separate multiple items that you specify by using the LIBPATH_PREFIX or LIBPATH_SUFFIX option.

DLL files that are on the library path for use by your applications must be compiled and linked with the XPLink option. Compiling and linking with the XPLink option provides optimum performance. The DLL files that are supplied on the base library path and the DLL files that are used by services such as the DB2 JDBC drivers are built with the XPLink option.

OSGI_BUNDLES=pathnames

Specifies the directory path for middleware bundles that are enabled in the OSGi framework of an OSGi JVM server. These OSGi bundles contain classes to implement system functions in the framework, such as connecting to WebSphere® MQ or DB2. If you specify more than one OSGi bundle, use commas to separate them.

OSGI_CONSOLE={TRUE|FALSE}

Adds the required OSGi bundles to the OSGi framework to enable the OSGi console. You must also set the following properties in the JVM profile: -Dosgi.console=host:port and -Dosgi.file.encoding={ISO-8859-1|US-ASCII|ASCII}. The default value is FALSE. If you want to look at the state of OSGi bundles and services, see Troubleshooting Java applications .

OSGI_FRAMEWORK_TIMEOUT={60|number}

Specifies the number of seconds that CICS waits for the OSGi framework to initialize or shut down before timing out. You can set a value in the range 1 - 60000 seconds. The default value is 60 seconds. If the OSGi framework takes longer to start than the specified number of seconds, the JVM server fails to initialize and a DFHSJ0215 message is issued by CICS. Error messages are also written to the JVM server log files in zFS. If the OSGi framework takes longer to shut down than the specified number of seconds, the JVM server fails to shut down normally.

PRINT_JVM_OPTIONS={TRUE|FALSE}

If this option is set to TRUE, whenever a JVM starts, the options that are passed to the JVM at startup are also printed to SYSPRINT. The output is produced every time a JVM starts with this option in its profile. You can use this option to check the contents of the class paths for a particular JVM profile, including the base library path and the base class path that are built by CICS, which are not visible in the JVM profile.

SECURITY_TOKEN_SERVICE={TRUE|FALSE}

If this option is set to TRUE, the JVM server can use security tokens. If this option is set to FALSE, Security Token Service support is disabled for the JVM server.

Note: The options SECURITY_TOKEN_SERVICE=TRUE and JAVA_PIPELINE=TRUE are not compatible.

STDERR={&APPLID;.&JVMSERVER;.Dyyyymmdd.Thhmmss.dfhjvmerr|file_name}

Specifies the name of the z/OS UNIX file to be used for stderr. You can specify an absolute or relative filename for STDERR. If you specify a relative filename the trace file will be created in the directory specified by the WORK_DIR option. If the file already exists, output is appended to the end of the file. If you specify an absolute filename then you must make sure that all the relevant directories are created on z/OS UNIX, and that the CICS regions are given read, write, and execute access to them. If you do not set a value for this option, CICS automatically creates unique trace files for each JVM server. CICS uses the &APPLID; and &JVMSERVER; symbols, and the date and time stamp when the JVM server started. This file is created in the directory that is specified by the WORK_DIR option.

If you specify the USEROUTPUTCLASS option on a JVM profile, the Java class that is named on that option handles the System.err requests instead. The z/OS UNIX file that is named by the STDERR option might still be used if the class named by the USEROUTPUTCLASS option cannot write data to its intended destination. This is the case when you use the supplied sample class com.ibm.cics.samples.SJMergedStream. You can also use the file if output is directed to it for any other reason by a class that is named by the USEROUTPUTCLASS option.

STDIN=file_name

Specifies the name of the z/OS UNIX file to be used for stdin. CICS does not create this file unless you specify a value for this option.

STDOUT={&APPLID;.&JVMSERVER;.Dyyyymmdd.Thhmmss.dfhjvmout|file_name}

Specifies the name of the z/OS UNIX file that is to be used for output to the stdout file. You can specify an absolute or relative filename for STDOUT. If you specify a relative filename the trace file will be created in the directory specified by the WORK_DIR option. If the file already exists, output is appended to the end of the file. If you specify an absolute filename then you must make sure that all the relevant directories are created on z/OS UNIX, and that the CICS regions are given read, write, and execute access to them. If you do not set a value for this option, CICS automatically creates unique trace files for each JVM server. CICS uses the &APPLID; and &JVMSERVER; symbols, and the date and time stamp when the JVM server started. This file is created in the directory that is specified by the WORK_DIR option.

If you specify the USEROUTPUTCLASS option in a JVM profile, the Java class that is named on that option handles the System.out requests instead. The z/OS UNIX file that is named by the STDOUT option might still be used if the class named by the USEROUTPUTCLASS option cannot write data to its intended destination; for example, when you use the sample class com.ibm.cics.samples.SJMergedStream. You can also use the file if output is directed to it for any other reason by a class that is named by the USEROUTPUTCLASS option.

USEROUTPUTCLASS=classname

Specifies the fully qualified name of a Java class that intercepts the output from the JVM and messages from JVM internals. You can use this Java class to redirect the output and messages from your JVMs, and you can add time stamps and headers to the output records. This is not supported for Liberty. If the Java class cannot write data to its intended destination, the files that are named in the STDOUT and STDERR options might still be used.

Specifying the USEROUTPUTCLASS option has a negative effect on the performance of JVMs. For best performance in a production environment, do not use this option. However, this option can be useful to application developers who are using the same CICS region because the JVM output can be directed to an identifiable destination.

For more information about this class and the supplied samples, see Controlling the location for JVM stdout, stderr, JVMTRACE, and dump output.

WLP_INSTALL_DIR={&USSHOME;/wlp}

Specifies the installation directory of the Liberty profile technology. The Liberty profile is installed in the z/OS UNIX home for CICS in a subdirectory called wlp. The default installation directory is /usr/lpp/cicsts/cicsts52/wlp. Always use the &USSHOME; symbol to set the correct file path and append the wlp directory.

This environment variable is required if you want to start a Liberty JVM server. If you set this environment variable, you can also supply other environment variables and system properties to configure the Liberty JVM server. The environment variables are prefixed with WLP, and the system properties are described in JVM system properties.

WLP_OUTPUT_DIR=WLP_USER_DIR/servers

Specifies the directory that contains output files for the Liberty profile. By default, the Liberty profile stores logs, the work area, configuration files, and applications, for the server in a directory that is named after the server.

This environment variable is optional. If you do not specify it, CICS defaults to &WORK_DIR;/&APPLID;/&JVMSERVER;/wlp/usr/servers/server_name, replacing the symbols with runtime values.

If this environment variable is set, the output logs and workarea are stored in ${WLP_OUTPUT_DIR}/server_name.

WLP_USER_DIR={&APPLID;/&JVMSERVER;/wlp/usr/|directory_path}

Specifies the directory that contains the configuration files for the Liberty JVM server. This environment variable is optional. If you do not specify it, CICS uses &APPLID;/&JVMSERVER;/wlp/usr/ in the working directory, replacing the symbols with runtime values. Configuration files are written to servers/server_name.

WLP_ZOS_PLATFORM=FALSE

Disables the z/OS platform extensions in a Liberty JVM server. This prevents the use the use of the cicsts:security-1.0 feature, and allows more than one Liberty JVM server to be started in the same region.

WORK_DIR={.|/tmp|directory_name|}

Specifies the working directory on z/OS UNIX that the CICS region uses for activities that are related to Java. The CICS JVM interface uses this directory when it creates the stdin, stdout, and stderr files. A period (.) is defined in the supplied JVM profiles, indicating that the home directory of the CICS region user ID is to be used as the working directory. This directory can be created during CICS installation. If the directory does not exist or if WORK_DIR is omitted, /tmp is used as the z/OS UNIX directory name.

You can specify an absolute path or relative path to the working directory. A relative working directory is relative to the home directory of the CICS region user ID. If you do not want to use the home directory as the working directory for activities that are related to Java, or if your CICS regions are sharing the z/OS user identifier (UID) and so have the same home directory, you can create a different working directory for each CICS region. You specify a directory name that uses the &APPLID; symbol, for which CICS substitutes the actual CICS region APPLID. So you can have a unique working directory for each region, even if all the CICS regions share the set of JVM profiles. For example, if you specify:

WORK_DIR=/u/&APPLID;/javaoutput

each CICS region that uses that JVM profile has its own working directory. Ensure that the relevant directories are created on z/OS UNIX, and that the CICS regions are given read, write, and execute access to them.

You can also specify a fixed name for the working directory. In this situation, you must also ensure that the relevant directory is created on z/OS UNIX, and access permissions are given to the correct CICS regions. If you use a fixed name for the working directory, the output files from all the JVM servers in the CICS regions that share the JVM profile are created in that directory. If you use fixed file names for your output files, the output from all the JVM servers in those CICS regions is appended to the same z/OS UNIX files. To avoid appending to the same files, use the &JVMSERVER; symbol and the &APPLID; symbols to produce unique output and dump files for each JVM server.

Do not define your working directories in the CICS directory on z/OS UNIX, which is the home directory for CICS files as defined by the USSHOME system initialization parameter.

You can also use the option USEROUTPUTCLASS to name a Java class that intercepts, redirects, and formats the stderr and stdout output from a JVM. The supplied sample classes for output redirection use the directory that is specified by WORK_DIR in some circumstances.

WSDL_VALIDATOR={TRUE|FALSE|}

Enables validation for SOAP requests and responses against their definition and schema. This option is ignored for Liberty JVM servers. For more information, see Validating SOAP messages. It is possible to turn off this option by setting WSDL_VALIDATOR=FALSE. Opting out can prevent potential clashes with newer JAR files, wasted storage, and slower startup.

ZCEE_INSTALL_DIR={<installation_directory>}

Provides the location of the z/OS Connect Enterprise Edition feature installation. For z/OS Connect EE V2.0, the default is /usr/lpp/IBM/zosconnect/v2r0/runtime. For z/OS Connect EE V3.0, the default is /usr/lpp/IBM/zosconnect/v3r0/runtime.