Options in JVM profiles

"Setting up JVM profiles and JVM properties files" in Java™ Applications in CICS® tells you how to set up suitable JVM profiles and JVM properties files to meet the needs of your applications.

The options that you can specify in JVM profiles can be divided into three groups:

Table 29 summarizes the options according to their function. Specify each option according to the coding rules described in Rules for coding JVM profiles and JVM properties files.

Notes:
  1. Remember that all parameter keywords and operands specified in a JVM profile or JVM properties file are case-sensitive, and must be specified exactly as shown in the following sections.
  2. Where a default value is indicated for a particular option, this is the default value that CICS uses when the option is not specified in the JVM profile. However, some or all of the CICS-supplied sample JVM profiles might specify a value that is different to the default value. For example, the default value for the Xverify option is remote, but the CICS-supplied sample JVM profiles specify the value none.
JVM profiles that specify CLASSCACHE=YES (for worker JVMs)

If you specify CLASSCACHE=YES in a JVM profile, the JVM uses the shared class cache, and is known as a worker JVM. Java Applications in CICS describes the shared class cache.

When you specify CLASSCACHE=YES in a JVM profile, certain options in the JVM profile and JVM properties file are ignored. If these options are found in the JVM profile or JVM properties file for a worker JVM, CICS does not pass them on to the JVM. If values for these options are required, they are taken from the JVM profile and JVM properties file for the master JVM that initializes the shared class cache. These options are not used in the CICS-supplied sample worker JVM profile DFHJVMPC. If you have converted another JVM profile to use the shared class cache, you can either remove the options (by commenting out or deletion) from the JVM profile or JVM properties file, or leave them there.

The options that are ignored because you specify CLASSCACHE=YES in a JVM profile are:

The java.compiler system property in the JVM properties file, which names the Java just-in-time compiler, is a special case. You can use this system property to specify that Java compiling should not be performed for a particular worker JVM, but otherwise it must match the java.compiler system property for the master JVM.

The following sections of this topic have more information about the JVM profile options in the list above, and the topic System properties for JVMs has more information about the system properties.

JVM profile for the master JVM that initializes the shared class cache

The JVM profile that is used for the master JVM that initializes the shared class cache is specified by the JVMCCPROFILE system initialization parameter. It can be changed using the PROFILE option on the CEMT PERFORM CLASSCACHE START or CEMT PERFORM CLASSCACHE RELOAD commands (or the equivalent EXEC CICS commands). Java Applications in CICS has more information about determining the JVM profile that is used for the master JVM. The CICS-supplied sample JVM profile for the master JVM is DFHJVMCC, and the JVM properties file that it references is dfjjvmcc.props.

The JVM profile for a master JVM is similar to the JVM profile for any other JVM. The CLASSCACHE_MSGLOG option can be specified to name the file for messages from the master JVM. One important decision to make about the master JVM is whether to define it as a resettable JVM (by specifying the option REUSE=RESET), or as a continuous JVM (by specifying the option REUSE=YES). It cannot be defined as a single-use JVM (REUSE=NO). The worker JVMs in a CICS region all have the same level of reusability as the master JVM in that region. Java Applications in CICS has more information to help you decide on an appropriate level of reusability for your worker JVMs.

Also, CICS ignores certain options in the JVM profile which are not needed for a master JVM, as follows:

The JVM properties file for a master JVM omits most of the system properties that would be specified for a normal JVM, because the master JVM is not used to run Java applications. The only system property that needs to be specified is ibm.jvm.shareable.application.class.path, which you should use to specify the shareable application classes for all the applications that will run in worker JVMs that use the shared class cache. You might also want to specify the system properties java.compiler and ibm.dg.trc.external, and the topic System properties for JVMs has information about these.

Customizing DFHJVMCD

The JVM profile DFHJVMCD is reserved for use by CICS-supplied system programs, in particular the default request processor program DFJIIRP (used by the CICS-supplied CIRP request processor transaction), to make them independent of any changes you make to the default JVM profile DFHJVMPR. DFHJVMCD has an associated JVM properties file, dfjjvmcd.props. Do not specify this profile in PROGRAM resource definitions that you set up for your own applications.

You need to make sure that DFHJVMCD is set up correctly for your CICS region, but you should customize it only where necessary. The options that you can change are indicated in the text of DFHJVMCD. You might need to change options in DFHJVMCD if:

In dfjjvmcd.props, you need to add the paths to classes for the applications using the request processor program to the shareable application class path (except for the deployed JAR files for enterprise beans, which do not need to be added to a class path). You also need to specify the system properties that are necessary to configure your JNDI nameserver and LDAP nameserver, and enable the Java 2 security policy mechanism (if required). System properties for JVMs has more information about the relevant system properties to change in dfjjvmcd.props.

Do not make any other changes to DFHJVMCD and dfjjvmcd.props.

Table 29 summarizes the main options that you can use in a JVM profile for CICS, and also some of the system properties that are normally suitable for a JVM properties file in a CICS environment. There are other possible system properties for JVMs which are not included in this table. Some are not included in the table because it is recommended that you should not normally change them, and these are listed in System properties for JVMs. Others are not included in the table, and are not listed in this document, because they are not normally relevant for a CICS environment. Remember that as noted in Rules for coding JVM profiles and JVM properties files, other documentation relating to the JVM lists further system properties, but only the system properties described in the CICS documentation are supported by CICS.

The table shows the default for each option if it is not specified in the JVM profile or JVM properties file. It also normally shows, for each type of JVM, whether the option is required (must be specified), OK (is valid), or ignored (CICS ignores the option if it is specified). If a particular setting for the option is required for a certain type of JVM, or if the option is only applicable to a certain type of JVM, then this information is given instead. The full description of each JVM profile option is in the list following the table, and the full description of the system properties mentioned here is in System properties for JVMs.

Table 29. Main options for a JVM profile and JVM properties file in a CICS environment
Option Default Where set Master Worker Standalone
JVM type
CLASSCACHE NO Profile Ignored YES NO
REUSE RESET Profile RESET or YES Ignored Any
Xresettable (deprecated) YES Profile YES Ignored Any
Directories
CICS_DIRECTORY none Profile Required Ignored Required
JAVA_HOME none Profile Required Ignored Required
WORK_DIR /tmp Profile OK OK OK
Class paths
CLASSPATH none Profile Ignored OK OK
LIBPATH none Profile Required Ignored Required
TMPREFIX, TMSUFFIX none Profile OK Ignored OK
ibm.jvm.shareable.application. class.path none Properties Required Ignored OK
Further settings and facilities for the JVM
JVMPROPS none Profile Required Required Required
INVOKE_DFHJVMAT NO Profile Ignored Ignored Single-use only
java.compiler jitc Properties OK OK OK
Start of changeMAX_RESETS_TO_GCEnd of change Start of change100End of change Start of changeProfileEnd of change Start of changeIgnoredEnd of change Start of changeOKEnd of change Start of changeResettable onlyEnd of change
Xrundllname none Profile OK OK OK
Storage heap sizes
Xinitacsh 128 KB Profile OK Ignored Resettable only
Xinitsh 128 KB Profile OK Ignored OK
Xinitth 500 KB Profile Ignored Resettable only Resettable only
Xmaxe, Xmaxf, Xmine, Xminf see listing Profile OK OK OK
Xms 500 KB Profile OK OK OK
Xmx 64 MB Profile OK OK OK
Xoss, Xss see listing Profile OK OK OK
Output from the JVM
CLASSCACHE_MSGLOG dfhjvmccmsg. log Profile Required Ignored Ignored
LEHEAPSTATS NO Profile OK OK OK
STDERR dfhjvmerr Profile OK OK OK
STDIN dfhjvmin Profile OK OK OK
STDOUT dfhjvmout Profile OK OK OK
USEROUTPUTCLASS none Profile Ignored OK OK
VERBOSE NO Profile OK OK OK
Security
java.security.manager none Properties OK OK OK
java.security.policy none Properties OK OK OK
Name server configuration
com.ibm.cics.ejs.nameserver none Properties OK OK OK
com.ibm.ws.naming.ldap.containerdn, com.ibm.ws.naming.ldap.noderootrdn none Properties OK OK OK
java.naming.security.authentication, java.naming.security.credentials, java.naming.security.principal none Properties OK OK OK
JDBC
com.ibm.cics.datasource.path none Properties OK OK OK
jdbc.drivers none Properties OK OK OK
Problem determination and application debugging
DISABLEASSERTIONS none Profile OK OK OK
ENABLEASSERTIONS none Profile OK OK OK
SYSTEMASSERTIONS none Profile OK Error OK
USE_LIBJVM_G NO Profile OK OK OK
Xcheck NO Profile OK OK OK
Xdebug NO Profile Ignored Ignored OK
Xverify remote Profile OK OK OK
ibm.dg.trc.external none Properties OK OK OK
ibm.jvm.crossheap.events none Properties OK OK OK
ibm.jvm.events.output event.log Properties OK OK OK
ibm.jvm.resettrace.events none Properties OK OK OK
ibm.jvm.unresettable.events.level none Properties OK OK OK
gateway.T properties (for tracing CICS Connector for CICS TS) none Properties OK OK OK

CICS-specific options

This set of JVM profile options is required only by CICS to enable CICS to start the JVM.

CICS_DIRECTORY=/usr/lpp/cicsts/cicsts31/
Specifies the path for the CICS HFS /lib subdirectory containing the CICS-supplied JAR files, such as dfjcics.jar, dfjorb.jar, ras.jar and so on. By default, /lib is installed in /usr/lpp/cicsts/cicsts31/, where cicsts31 is defined by the USSDIR installation parameter when you installed CICS TS for z/OS®, Version 3.1. For more information about this installation parameter, see &CICS_DIRECTORY.

This parameter is required in JVM profiles where you have specified CLASSCACHE=NO (or where you have not specified the CLASSCACHE option at all). It is used by CICS to build the trusted middleware class path.

In JVM profiles where you have specified CLASSCACHE=YES (that is, the JVM profiles for worker JVMs), this option is ignored. Its value is taken instead from the JVM profile for the master JVM that initializes the shared class cache. The CICS-supplied sample JVM profile for the master JVM is DFHJVMCC.

CLASSCACHE={YES|NO}
Specifies whether this JVM is to use the shared class cache. The default is NO. Java Applications in CICS describes the shared class cache. A JVM that uses the shared class cache is known as a worker JVM. Single-use JVMs or JVMs that are configured for debug cannot use the shared class cache.

When you specify CLASSCACHE=YES in a JVM profile, certain options in the JVM profile and JVM properties file are ignored. If these options are found in the JVM profile or JVM properties file for a worker JVM, CICS does not pass them on to the JVM. If values for these options are required, they are taken from the JVM profile and JVM properties file for the master JVM that initializes the shared class cache. The introduction to this topic explains which options and system properties are affected.

The CLASSCACHE option is ignored if it is specified in the JVM profile used for the master JVM that initializes the shared class cache.

In JVM profiles where you have specified CLASSCACHE=YES, in a production environment, you should avoid using the CLASSPATH option (the standard class path) to specify application classes. If you do use this option, if the JVM is resettable, the classes are reloaded each time the JVM is reused. This is detrimental to performance, and means that the JIT compiler will generate less-than-optimal code for those classes. Instead, you should place the application classes on the ibm.jvm.shareable.application.class.path system property in the JVM properties file that is used for the master JVM that initializes the shared class cache.

CLASSCACHE_MSGLOG={dfhjvmccmsg.log|filename}
Specifies the name of an HFS file allocated in WORK_DIR, to which messages are written from the master JVM that initializes the shared class cache. If no file name is specified, or if the option is not included, the default file name dfhjvmccmsg.log is used. This option is only used on the JVM profile for the master JVM that initializes the shared class cache. If it is specified on any other JVM profile, it is ignored.
INVOKE_DFHJVMAT={NO|YES}
Specifies whether or not the user replaceable module, DFHJVMAT, should be invoked before creating a new JVM. DFHJVMAT can only be used for single-use JVMs, that is, where the option REUSE=NO or the older option Xresettable=NO is specified in the JVM profile. INVOKE_DFHJVMAT is ignored if the JVM is a resettable JVM or a continuous JVM, which is the case if any of the following options are specified in the JVM profile:
JAVA_HOME=/usr/lpp/java142/J1.4/
Specifies the path for IBM Software Developer Kit for z/OS, Java 2 Technology Edition, Version 1.4.2 subdirectories and JAR files. By default, the Java subdirectories and JAR files are installed in /usr/lpp/java142/J1.4/, where /java142/J1.4/ is defined when you install IBM Software Developer Kit for z/OS, Java 2 Technology Edition, Version 1.4.2.

The JAVA_HOME directory is also the value you specify on the JAVADIR CICS installation parameter. For more information, see &JAVA_HOME.

This parameter is required in JVM profiles where you have specified CLASSCACHE=NO (or where you have not specified the CLASSCACHE option at all). In JVM profiles where you have specified CLASSCACHE=YES (that is, the JVM profiles for worker JVMs), this option is ignored. Its value is taken instead from the JVM profile for the master JVM that initializes the shared class cache. The CICS-supplied sample JVM profile for the master JVM is DFHJVMCC.

JVMPROPS=path/file_name
Specifies the path and name of a JVM properties file, which is a HFS file that contains the system properties for this JVM. The values in this file are passed to the JVM for the construction of system properties as if specified by a -D option in a java command. System properties for JVMs tells you what you can specify in a JVM properties file.
LEHEAPSTATS={YES|NO}
Specifies whether or not statistics are to be collected for the amount of Language Environment® heap storage that is used by the JVM. The default is NO. The statistics appear as the field "Peak Language Environment heap storage used" in the JVM Profile statistics. Collecting these statistics affects the performance of the JVM, so you should only specify LEHEAPSTATS=YES while you are in the process of tuning the heap sizes for your JVMs. ("Java applications using a Java virtual machine (JVM): improving performance" in the CICS Performance Guide explains this process.) In a production environment, you should specify LEHEAPSTATS=NO.
LIBPATH=pathnames
Specifies the directory paths to be searched for native C dynamic link library (DLL) files that are used by the JVM (which have the extension .so in z/OS UNIX), including those required to run the JVM and additional native libraries loaded by trusted code.

The directory paths set in the CICS-supplied sample JVM profiles are created automatically using the symbols &CICS_DIRECTORY and &JAVA_HOME. The DFHIJVMJ job substitutes appropriate values for these symbols during CICS installation (see the CICS Transaction Server for z/OS Installation Guide). The directory paths that are created by this process include the path to the native C DLL files required to support JCICS.

If CLASSCACHE=YES is specified to make the JVM a worker JVM, this option is ignored. Its value is taken instead from the library path specified in the JVM profile for the master JVM that initializes the shared class cache. If you have added directory paths (for example, the DB2-supplied directory containing dynamic load libraries for the JDBC drivers) to this option in the JVM profile for a worker JVM, ensure that you transfer them to the corresponding option in the JVM profile for the master JVM. The CICS-supplied sample JVM profile for the master JVM is DFHJVMCC. Note that the master and worker JVMs use the same LIBPATH specification to ensure that they are using the same versions of the files on the library path. However, these files are not loaded into the shared class cache. Unless they are shared through another z/OS facility (such as the shared library region), a copy is loaded into each worker JVM.

Start of changeMAX_RESETS_TO_GC={100|number}End of change
Start of changeSpecifies when the garbage collection cycle is started in CICS. The value is the number of times a JVM is used. The default is 100, and you can set a minimum value of 1 and a maximum value of 2147483647 (231--1).End of change
REUSE={RESET|YES|NO}
Specifies the level of reusability for the JVM. "How JVMs are reused and reset" in Java Applications in CICS gives a full explanation of the characteristics of the three possible levels of reusability for a JVM, the situations and application designs for which each level of reusability is appropriate, and the relative performance of each level of reusability. The settings for this option specify the levels of reusability as follows: The level of reusability that you choose might affect the relevance of some of the storage heap size options in the JVM profile. The options that might be affected are Xinitacsh, Xinitth, Xmaxe, Xmine, Xmaxf, Xminf, and Xmx. Depending on the level of reusability, you might be able to omit these options from the JVM profile, or their meaning might change. See the descriptions of these options later in this section for more information.

When you are choosing a setting for the REUSE option in a JVM profile, follow these rules:

  1. If the option CLASSCACHE=YES is specified in the JVM profile, to make the JVM a worker JVM, the REUSE option is ignored. Worker JVMs inherit their level of reusability from the master JVM. Do not specify both CLASSCACHE=YES and the REUSE option.
  2. If the JVM profile is to be used for the master JVM that initializes the shared class cache, it can specify REUSE=RESET (to create a resettable JVM) or REUSE=YES (to create a continuous JVM). The master JVM cannot be a single-use JVM (REUSE=NO), and if you specify that setting, CICS disallows it and assumes instead that the master JVM is resettable. If the REUSE option is omitted, CICS also assumes that the master JVM is resettable. The worker JVMs in a CICS region all inherit their level of reusability from the master JVM in that region.
  3. If you specify the REUSE option, it is advisable to remove the older option Xresettable from the JVM profile, if it is present. This option was the previous method of specifying the level of reusability for a JVM. For migration purposes, it is still a valid way to create a resettable JVM (which is specified by Xresettable=YES) or a single-use JVM (which is specified by Xresettable=NO), but it cannot be used to create a continuous JVM. If both the Xresettable option and the REUSE option are specified, an error message is issued if their settings conflict, but the REUSE option overrides the Xresettable option. The Xresettable option is not used in the CICS-supplied sample JVM profiles.

If you specify REUSE=RESET or REUSE=YES in a JVM profile, remember that for successful reuse of JVMs created using that profile, you should:

STDERR={dfhjvmerr|file_name} [ -generate]
Specifies the name of the HFS file to be used for stderr. If the file does not exist, it is created in the directory specified by the WORK_DIR option. If the file already exists, output is appended to the end of the file. On termination of the JVM, if the stderr file is empty and it has been generated for the specific JVM, it is deleted. Otherwise, the file is kept.

The default name for the file is dfhjvmerr. Note that for a fixed file name, the output from multiple JVMs is appended to the named file, and the output is interleaved.

You can use in your file name the &APPLID; symbol , for which CICS substitutes the actual CICS region APPLID.

-generate
Specifies that you want CICS to generate the output file name for a specific JVM by appending the following qualifiers to the name supplied on the generate option:
region
The applid of the CICS region
time
The current time in the form yydddhhmmss.
.txt
A literal string suffix to indicate that the file contains readable data and should be transferred with character translation by tools such as FTP.

-generate must be preceded by one blank.

The use of the -generate option is not recommended in a production environment, because it can be detrimental to the performance of your JVMs.

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

STDIN={dfhjvmin|file_name}
Specifies the name of the HFS file to be used for stdin. If the file does not exist, it is created in the directory specified by the WORK_DIR option.
STDOUT={dfhjvmout|file_name} [ -generate]
Specifies the name of the HFS file that is to be used for output to the stdout file. If the file does not exist, it is created in the directory specified by the WORK_DIR option. If the file already exists, output is appended to the end of the file. On termination of the JVM, if the stdout file is empty and it has been generated for the specific JVM, it is deleted. Otherwise, the file is kept.

The default name for the file is dfhjvmout. Note that for a fixed file name, the output from multiple JVMs is appended to the named file, and the output is interleaved.

You can use in your file name the &APPLID; symbol , for which CICS substitutes the actual CICS region APPLID.

For details of the -generate option, see the STDERR option. -generate must be preceded by one blank.

If you specify the USEROUTPUTCLASS option on a JVM profile, the Java class named on that option handles the System.out requests instead. The HFS file named by the STDOUT option could still be used if the class named by the USEROUTPUTCLASS option is unable to write data to its intended destination. This is the case when you use the CICS-supplied sample class com.ibm.cics.samples.SJMergedStream. The file could also be used if output is directed to it for any other reason by a class named by the USEROUTPUTCLASS option.

TMPREFIX=path_name, TMSUFFIX=path_name
Specify paths to be added to the trusted middleware class path that CICS generates automatically from the CICS_DIRECTORY parameter. The paths specified on TMPREFIX are inserted at the beginning of the CICS-generated ibm.jvm.trusted.middleware.class.path system property. The paths specified on TMSUFFIX are added to the end of the CICS-generated ibm.jvm.trusted.middleware.class.path system property. Do not edit the ibm.jvm.trusted.middleware.class.path system property directly.

If you want to access DB2 from a Java application program using the SQLJ and JDBC APIs, you need to add a DB2-supplied zip file (or for the DB2 Universal JDBC Driver, three DB2-supplied jar files) to the trusted middleware class path. "Using JDBC and SQLJ to access DB2 data from Java programs and enterprise beans written for CICS" in the CICS DB2 Guide explains how to do this for various levels of the DB2-supplied JDBC drivers.

Middleware classes have privileges that are not available to the application, and which enable optimizations through the caching of state (loading of classes and native libraries, for example) to be used by multiple applications, even if the JVM is resettable. However, middleware is also responsible for resetting itself correctly at the end of a transaction and, if necessary, for reinitializing at the beginning of a new transaction, in order to isolate different applications from each other.

You might need to specify paths to classes for middleware supplied by IBM or by another vendor, which are not included in the standard JVM setup for CICS. However, you should not use the trusted middleware class path parameters to specify paths to your own application classes, because you cannot subject trusted middleware classes to the same restrictions that might be appropriate for application classes. Classes on the trusted middleware class path could make changes to the JVM environment, or could create objects in one invocation of an application that could persist and interfere with the next invocation, or with the invocation of a completely different application. This is the case even when the JVM is resettable, and you might not want to permit your own application classes to perform these actions. Place your own application classes on the shareable application class path or the standard class path, because then you can use the REUSE option in the JVM profile to restrict the scope of their activities as necessary.

In JVM profiles where you have specified CLASSCACHE=YES (that is, the JVM profiles for worker JVMs), the options relating to the trusted middleware class path are ignored. Their value is taken instead from the JVM profile for the master JVM that initializes the shared class cache. Any paths that you have specified using these options in the JVM profiles for worker JVMs, must be copied to the TMPREFIX or TMSUFFIX option in the JVM profile for the master JVM. The CICS-supplied sample JVM profile for the master JVM is DFHJVMCC.

USE_LIBJVM_G={YES|NO}
Specifying USE_LIBJVM_G=YES enables the debug libraries for the JVM. If you specify NO or omit the option, the optimized libraries are used. Note that when you are using the debug libraries, extra checking takes place, so performance is greatly reduced compared to the use of the the normal, optimized libraries.

This option should be used only under the direction of IBM service.

USEROUTPUTCLASS={classname}
Specifies the fully qualified name of a Java class that is used to redirect output from this JVM. The class that you specify using the USEROUTPUTCLASS option extends java.io.OutputStream, and it handles all System.err and System.out requests from Java programs running in the JVM. CICS also uses this class to handle internal messages from the JVM, and event messages that are directed to the destination specified in the ibm.jvm.events.output system property in the JVM properties file for the JVM (depending on the setting for that system property).

If you do not specify the USEROUTPUTCLASS option in a JVM profile, or if you specify it as null, the HFS files named by the STDOUT and STDERR options in the profile are used for output from the JVM. If you specify the USEROUTPUTCLASS option in a JVM profile, the HFS files named by the STDOUT and STDERR options in the profile could be used if the class named by the USEROUTPUTCLASS option is unable to write data to its intended destination.

This option is irrelevant in the JVM profile for the master JVM that initializes the shared class cache, because the output redirection class will never be invoked by the activities of the master JVM.

CICS supplies the sample class com.ibm.cics.samples.SJMergedStream, which produces merged log files containing the output from all JVMs with identifying headers, and the alternative sample class com.ibm.cics.samples.SJTaskStream, which produces HFS files containing the output from a single task. "Redirecting JVM output" in Java Applications in CICS describes the behaviour of these classes. The classes are shipped as a middleware class file dfjoutput.jar, which is in the directory /usr/lpp/cicsts/cicsts31/lib, where cicsts31 is a user-defined value that you chose for the CICS_DIRECTORY variable used by the DFHIJVMJ job during CICS installation. The source for the classes is also provided as samples, so you can modify the classes as you want, or write your own classes based on the samples.

The class that you are using must be present in a directory on the trusted middleware class path used by the JVM (to which you can add paths by using the TMPREFIX or TMSUFFIX option in the JVM profile). If you are using your own class in place of the supplied sample class, any associated native code for your class must be present on the library path used by the JVM, and must be explicitly loaded using the System.loadLibrary() call, either at class load time via a static initializer, or in the class constructor. (This avoids the need to include doPrivileged() blocks around the loadLibrary call when you are running with Java security active.) Note that if the JVM is to use the shared class cache (if CLASSCACHE=YES is specified in the JVM profile), you will need to include the class and any associated native code in the trusted middleware class path and library path that are specified in the JVM profile for the master JVM that initializes the shared class cache, rather than those specified in the JVM profile for the JVM itself. The CICS-supplied sample JVM profile for the master JVM is DFHJVMCC, and the JVM properties file that it references is dfjjvmcc.props.

The Java programs that will run in JVMs that use the USEROUTPUTCLASS option should include appropriate exception handling to deal with the exceptions that might be thrown by the class named on the USEROUTPUTCLASS option. The CICS-supplied sample classes handle all exceptions internally, so they do not return any errors to the calling program.

Specifying the USEROUTPUTCLASS option has a negative effect on the performance of JVMs. For best performance in a production environment, you should not use this option. However, it can be useful to specify the USEROUTPUTCLASS option during application development. This is because if you do not specify USEROUTPUTCLASS, the output from all JVMs goes to the files specified by the STDOUT and STDERR options in the JVM profile. You can generate separate versions of these files for each JVM, but these files can only be differentiated by the applid of the CICS region and the time of generation. The USEROUTPUTCLASS option enables developers using the same CICS region to separate out their own JVM output, and direct it to an identifiable destination of their choice.

WORK_DIR={.|directory_name}
Specifies the working directory on HFS that the CICS region uses for Java-related activities. The CICS JVM interface uses this directory when creating the stdin, stdout and stderr files. A period (.) is defined in the CICS-supplied JVM profiles, which means that the home directory of the CICS region user ID (that is, the HFS directory /u/CICS region userid) is to be used as the working directory. You can create this directory when you follow the process described in "Giving CICS regions access to UNIX system services and HFS directories and files" in Java Applications in CICS. If the CICS region user ID does not have this home directory, or if WORK_DIR is omitted altogether, /tmp is used as the HFS directory name.

You can create a subdirectory within this HFS directory to hold the output files, by specifying the subdirectory name after the period. For example, if you specify:

WORK_DIR=./javaoutput

then the output files from all the JVMs in that CICS region are created in the subdirectory javaoutput in the home directory of the CICS region userid.

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

WORK_DIR=/u/&APPLID;/javaoutput

then each CICS region using that JVM profile will have its own working directory. If you do this, ensure that you have created all the relevant directories on HFS and given the CICS regions read, write and execute access to them, as described in "Giving CICS regions access to UNIX system services and HFS directories and files" in Java Applications in CICS.

It is also possible to specify a fixed file name for the working directory, again ensuring that you have created the relevant directory on HFS and given the CICS regions the correct access. Bear in mind that when you use a fixed file name for the working directory, the output files from all the JVMs in the CICS regions that share the JVM profile are created in that directory. If you have also used fixed file names for your output files, the output from all the JVMs in those CICS regions will be appended to the same HFS files. If you want to avoid this, you can use -generate with the STDERR and STDOUT options to generate individual HFS files for each JVM in each CICS region. However, note that the use of the -generate option is not recommended in a production environment, because it can be detrimental to the performance of your JVMs.

You are recommended not to define your working directories within the CICS directory on HFS that contains the CICS-supplied Java code (the directory specified by the CICS_DIRECTORY option in the JVM profile, which by default is /usr/lpp/cicsts/cicsts31/).

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 CICS-supplied sample classes for output redirection use the directory specified by WORK_DIR in some circumstances.

Related reference
Java standard options
Java nonstandard options

Java standard options

The following Java standard options are passed by CICS to the JVM when the JVM is being launched:

CLASSPATH=class_pathnames
Specifies the directory paths to be searched by the JVM for nonshareable application classes and resources--that is, application classes that you do not want to be shared by other JVMs or across JVM resets. If the JVM is defined as resettable, classes on this class path are discarded when the JVM is reset, and reloaded from HFS files each time the JVM is reused. If the JVM is defined as a continuous JVM, however, nonshareable application classes are kept intact from one JVM reuse to the next. If the JVM is defined as a worker JVM, nonshareable application classes are not placed in the shared class cache. This class path is known as the standard class path. In CICS, this option in the JVM profile is used instead of the java.class.path option in the JVM properties file. This option is ignored if it is specified in the JVM profile used for the master JVM that initializes the shared class cache, because applications cannot run in the master JVM.

If the JVM is a resettable JVM, which is the case if the option REUSE=RESET (or the older option Xresettable=YES) is specified in the JVM profile, you should avoid using the CLASSPATH option in a production environment, because it is detrimental to performance. If the JVM is a worker JVM (either resettable or continuous), which is the case if the option CLASSCACHE=YES is specified in the JVM profile, using the CLASSPATH option increases storage usage, because the classes are stored in every JVM instead of just in the master JVM. Instead, use the ibm.jvm.shareable.application.class.path system property. For standalone JVMs with CLASSCACHE=NO in their JVM profile, this system property is specified in the JVM properties file for the JVM, but for worker JVMs with CLASSCACHE=YES in their JVM profile, it is specified in the JVM properties file for the master JVM that initializes the shared class cache.

You can specify directory paths on separate lines by using a \ (backslash) at the end of each line that is to be continued.

If any of your Java application programs are built as a package (that is, compiled using a Java package statement), do not include the package name as part of the path name on CLASSPATH.

For example, the source of the CICS HelloCICSWorld sample program begins with:

 package examples.HelloWorld;

In this case, the package name should be included in the class name in the CICS program resource definition; for example, as JVMCLASS(examples.HelloWorld.HelloCICSWorld).

When you create the sample program using the supplied HelloCICSWorld.mak makefile, it is installed in the /examples/HelloWorld/ subdirectories. For example, if you build the samples in the default directories created when you installed CICS TS, the full path is

 /usr/lpp/cicsts/cicsts31/samples/dfjcics/examples/HelloWorld/

The correct CLASSPATH to enable the JVM to find this Java program is

CLASSPATH=/usr/lpp/cicsts/cicsts31/samples/dfjcics

omitting the package name.

DISABLEASSERTIONS={ALL|packageName...|className}
Disables assertion checking for the specified code at run time. For details of the syntax, and the rules for using this option with applications that run in worker JVMs, see the ENABLEASSERTIONS option.
ENABLEASSERTIONS={ALL|packageName...|className}
Enables assertion checking for the specified code at run time. An assertion is a statement in the Java programming language that enables you to test your assumptions about your program. You can specify that assertions should be enabled in a package and in any subpackages that it has (the ... after the package name ensures that any subpackages are included), or in an individual class. Specifying ALL enables assertions in all classes except system classes.

You can specify more than one option relating to assertions in the JVM profile. For example, you could use the ENABLEASSERTIONS option to specify a package for which you want to enable assertions, and then use the DISABLEASSERTIONS option to disable assertions for a particular class within that package. However, note that CICS does not support the use of multiple instances of the same option relating to assertions. For example, you cannot specify the DISABLEASSERTIONS option twice in order to disable assertions for two individual classes.

If you are using assertions with applications that run in worker JVMs (JVMs that share the class cache), the following rules apply:

You can find more information about programming with assertions, and about enabling and disabling assertions, at http://java.sun.com/j2se/1.4.1/docs/guide/lang/assert.html.

SYSTEMASSERTIONS={ON|OFF}
Enables or disables assertion checking for all system classes in the JVM. To enable or disable assertion checking for individual system classes, use the ENABLEASSERTIONS and DISABLEASSERTIONS options as you would for any other classes.

The SYSTEMASSERTIONS option can be specified in a master JVM, but it causes an error in a worker JVM (because the worker JVM does not have its own system heap). If you want to enable or disable assertions for system classes used by an application that runs in a worker JVM, specify the SYSTEMASSERTIONS option in the JVM profile for the master JVM.

VERBOSE={NO|[class][,gc][,jni]}
Indicates whether or not the JVM should issue a message containing information about its activities. You can specify any or all of the three available options, or none. The options are:
NO
Omit the verbose option so that the JVM does not report any of the information messages described by the following options.
class
Specifies that the JVM is to report information about each class it loads. This equates to the standard JVM launcher option -verbose (or -verbose:class) defined in the persistent reusable JVM Java 2 specification.
gc
Specifies that the JVM should issue a message to report each garbage collection event. This equates to the standard JVM launcher option -verbose:gc defined in the persistent reusable JVM specification.
jni
Specifies that the JVM should issue a message each time it performs one of the following Java native interface (JNI) operations:
  • Dynamic link of a native method
  • Registers a native method
  • Loads a native library.
This equates to the standard JVM launcher option -verbose:jni defined in the persistent reusable JVM specification.
Coding examples:
verbose=class
verbose=class,jni
verbose=gc

Java nonstandard options

The following are the nonstandard options that are supported by the IBM persistent reusable JVM.

Note:
Specify storage sizes in multiples of 1024 bytes. Use the letter K to indicate kilobytes, the letter M to indicate megabytes, and the letter G to indicate gigabytes. For example, to specify 6291456 bytes as the initial size of the middleware heap, code Xms in one of the following ways:
Xms=6291456
Xms=6144K
Xms=6M
Xcheck={NO|[jni][,nabounds]}
Specifies whether or not you want the JVM to perform additional checks. There are two options, and you can specify either of these or both.
jni
Performs additional checks for JNI functions
nabounds
Performs a native-array bounds check for JNI functions.

If you omit the jni option, also omit the comma in front of nabounds.

Xdebug={NO|YES}
Specifies whether or not debugging support is to be enabled in the JVM. See also the Xrunjdwp debug invocation option.

For more information , see "Using a debugger with the JVM" in Java Applications in CICS. See also the Java Platform Debugger Architecture (JPDA) description at http://java.sun.com/products/jpda/doc/.

To ensure clean termination of the debug session, specify REUSE=NO (or the older option Xresettable=NO) when debugging support is enabled.

In JVM profiles where you have specified CLASSCACHE=YES (that is, the JVM profiles for worker JVMs), this option is ignored. It is also ignored in the JVM profile for the master JVM that initializes the shared class cache. Worker JVMs and the master JVM cannot be configured for debug.

Xinitacsh={128KB|size}
Specifies the initial size of the application-class system heap for resettable JVMs. This option is ignored for continuous and single-use JVMs (those with REUSE=YES, REUSE=NO or Xresettable=NO in their JVM profile), because these types of JVM do not have an application-class system heap. It is also ignored for worker JVMs (those with CLASSCACHE=YES in their JVM profile), because worker JVMs use the master JVM's system heap.

Specify size as a number of bytes, kilobytes, or megabytes (see Specifying storage sizes). The default is 128KB.

Xinitsh={128KB|size}
Specifies the initial system heap size. The JVM does not enforce any maximum heap size. This option is ignored for worker JVMs (those with CLASSCACHE=YES in their JVM profile), because worker JVMs use the master JVM's system heap.

Specify size as a number of bytes, kilobytes, or megabytes (see Specifying storage sizes). The default is 128KB.

Xinitth={500KB|size}
Specifies the initial transient heap size. This option only applies to resettable JVMs. It is ignored for:

The storage for the transient heap is allocated from the high-end of the storage area allocated by the Xmx option, and is allowed to expand down until it meets the boundary of the middleware heap (specified by the Xms option).

Specify size as a number of bytes, kilobytes, or megabytes (see Specifying storage sizes). The default is 500KB. If Xinitth is not specified and Xms (which sets the initial size of the middleware heap) is specified, then Xinitth is set to half of Xms.

Xmaxe={0|size}
Specifies the maximum heap expansion size for the middleware and transient heaps. Continuous and single-use JVMs (those with REUSE=YES, REUSE=NO or Xresettable=NO in their JVM profile), and the master JVM that initializes the shared class cache, have no transient heap, so for those JVMs the value only applies to the middleware heap.

Specify size as a number of bytes, kilobytes, or megabytes (see Specifying storage sizes). The default is 0 (there is no maximum heap expansion size).

Xmaxf={0.6|number}
Specifies the maximum percentage of free space for the middleware heap, as a number between 0 and 1. This value applies only to the middleware heap and not to the transient heap (if the JVM has one). The default is 0.6 (that is, 60%). If a value less than 1 is specified and more free space is available than the value specified, the middleware heap is shrunk. A value of 0 allows no free space in the heap, and so heap contraction is a constant activity. A value of 1 means that the heap never contracts.
Xmine={1MB|size}
Specifies the minimum heap expansion size for the middleware and transient heaps. Continuous and single-use JVMs (those with REUSE=YES, REUSE=NO or Xresettable=NO in their JVM profile), and the master JVM that initializes the shared class cache, have no transient heap, so for those JVMs the value only applies to the middleware heap.

Specify size as a number of bytes, kilobytes, or megabytes (see Specifying storage sizes). The default is 1MB.

Xminf={0.3|number}
Specifies the minimum percentage of free space for the middleware and transient heaps. Continuous and single-use JVMs (those with REUSE=YES, REUSE=NO or Xresettable=NO in their JVM profile), and the master JVM that initializes the shared class cache, have no transient heap, so for those JVMs the value only applies to the middleware heap. As for the Xmaxf option, this is specified as a number between 0 and 1. The default is 0.3 (that is, 30%). If the free space falls below this amount, the heap grows.
Xms={500KB|size}
Specifies the initial size of the middleware heap. The storage for the middleware heap is allocated from the low-end of the storage area allocated by the Xmx option, and is allowed to expand up until it meets the boundary of the transient heap (specified by the Xinitth option).

Specify size as a number of bytes, kilobytes, or megabytes (see Specifying storage sizes). The default is 500KB.

Xmx={64MB|size}
Specifies the maximum total size of the middleware and transient heaps (that is, the size of the non-system heap). Note that this fixed amount of storage is allocated by the JVM during JVM initialization. The middleware heap grows from the bottom of this region, and the transient heap grows from the top of the region.

Continuous and single-use JVMs (those with REUSE=YES, REUSE=NO or Xresettable=NO in their JVM profile), and the master JVM that initializes the shared class cache, do not have a transient heap, so for these JVMs, the value of Xmx sets the maximum size for the middleware heap.

Specify size as a number of bytes, kilobytes, or megabytes (see Specifying storage sizes). The default is 64MB.

Xnoclassgc={NO|YES}
Specifies whether or not you want CICS to include the Xnoclassgc option on JVM launch command.
NO
Omitting the option means that the JVM performs class garbage collection.
YES
The option is specified on the JVM launch command, which means that class garbage collection is not performed.
Xoss={400KB|size}
Specifies the maximum size of the Java code stack for each thread. Each Java thread has two stacks: one for Java code and one for C code. This option sets the maximum stack size that can be used by Java code in a thread.

This option does not affect the allocation of storage, but the JVM uses it to check whether the specified limit has been exceeded, in which case the JVM throws a Java StackOverflowException.

Specify size as a number of bytes, kilobytes, or megabytes (see Specifying storage sizes). The default size is 400KB.

Xquickstart
See the Xservice="-Xquickstart" option.
Xresettable={YES|NO}
This option is a deprecated method of specifying the level of reusability for a JVM. "How JVMs are reused and reset" in Java Applications in CICS explains the three levels of reusability that a JVM can have. For migration purposes, the Xresettable option is still a valid way to create a resettable JVM (which is specified by Xresettable=YES) or a single-use JVM (which is specified by Xresettable=NO), but it cannot be used to create a continuous JVM. You should now use the REUSE option in the JVM profile to specify the level of reusability for the JVM. The CICS-supplied sample JVM profiles use the REUSE option instead of the Xresettable option.

When you use the REUSE option, it is advisable to remove the Xresettable option from the JVM profile, although if the options conflict the REUSE option overrides the Xresettable option. An information message is issued if this happens.

Xrs={NO|YES}
Specifies whether or not you want CICS to include the Xrs option on the JVM launch command. Xrs reduces the use of operating system signals by the JVM.
Xrundllname=(suboption=value,suboption=value...)
Loads the specified dynamic link library (DLL) and passes it the list of options. This option is typically specified as a list of sub-options of the form <suboption=value>, with each sub-option separated by a comma. You can load as many DLLs as you want, by repeating the Xrundllname option. The DLLs that you specify using the Xrundllname option must be present in directories on the library path for the JVM, which is specified by the LIBPATH option in the JVM profile.

Some useful DLLs that you can load using this option are:

CICS uses the Xrundllname option to load dfhapjvmt, which drives the JVMRAS interface to perform tracing. CICS specifies this option automatically when it is required.

Start of changeXservice="-Xquickstart"End of change
Start of changeDepending on your application, specifying this option in a JVM profile can provide some reduction in the startup time for those JVMs. The Xservice="-Xquickstart" option causes the just-in-time (JIT) compiler function of the JVM to omit certain optimizations when a method is first compiled. If the method is used frequently enough, the JIT compiler compiles it again using all the optimizations. This technique improves startup time for the JVM, but performance can be degraded on subsequent reuses of the JVM, because the code is not fully optimized or because of the time required for the second compile.End of change
Xss={500KB|size}
Specifies the maximum size of the native code stack for each thread. Each Java thread has two stacks: one for Java code and one for C code. This option sets the maximum stack size that can be used by C code in a thread.

This option does not affect the allocation of storage, but the JVM uses it to check whether the specified limit has been exceeded, in which case the JVM throws a Java StackOverflowException.

Specify size as a number of bytes, kilobytes, or megabytes (see Specifying storage sizes). The default is 500KB. At least 1KB must be specified.

Xverify={remote|all|none}
Specifies the level of verification you want the JVM to perform on classes to be loaded. When class files are loaded (possibly over the network or from an untrusted source) into a JVM, there is no way of telling how their byte codes were generated.

The options are:

remote
Verify only those classes that are loaded over the network. The default verification setting means that anything installed locally is not verified. This option equates to the Java command line option Xverify:remote.
all
Verify everything. This option equates to the Java command line option Xverify:all.
none
Do not perform any verification. This option equates to the Java command line option Xverify:none.

The CICS-supplied sample JVM profiles specify Xverify=none.

For worker JVMs that use the shared class cache (those with CLASSCACHE=YES in their JVM profile), this option only operates on classes that are on the standard class path (specified by the CLASSPATH option in the JVM profile). Other classes, on the shareable application class path or the middleware class path, are verified according to the verification setting specified for the master JVM that initializes the shared class cache.

Related tasks

Setting up JVM profiles and JVM properties files
Setting up the shared class cache
Redirecting JVM output
Using DFHJVMAT to modify options in a JVM profile
Using JDBC and SQLJ to access DB2 data from Java programs and enterprise beans written for CICS
Related concepts

The structure of a JVM
How CICS creates JVMs
The shared class cache
Related reference
CICS-specific options
Java standard options
Rules for coding JVM profiles and JVM properties files
System properties for JVMs
The sample JVM profiles and JVM properties files
[[ Contents Previous Page | Next Page Index ]]