"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.
System properties are key name and value pairs that contain basic information about the JVM and its environment, such as the operating system in which the application is running. The system properties are initialized when the JVM is first created. Some are set by the JVM automatically when it is initialized, and others you can specify in a JVM properties file, which is referenced by the JVMPROPS option in the JVM profile (see Options in JVM profiles).
CICS passes all the system properties in a JVM properties file to the JVM unchanged. However, you should bear in mind that only the system properties described in the CICS documentation are supported by CICS, although the JVM can support a much wider range of system properties. This topic documents the system properties that are particularly relevant for JVMs in a CICS environment, including some which are defined by CICS. Persistent Reusable Java Virtual Machine User's Guide, SC34-6201, lists command-line options, JVM options and system properties that are used in a persistent reusable JVM in a z/OS® environment, some of which are provided in a different format by options in the JVM profile in CICS. The IBM® Developer Kit and Runtime Environment, Java 2 Technology Edition, Version 1.4.2 Diagnostics Guide, SC34-6358, which is available to download from www.ibm.com/developerworks/java/jdk/diagnosis/, documents further system properties that are used for JVM trace and problem determination. The Java class libraries include other system properties, and applications might have their own system properties. There is no central repository of all system properties for the JVM.
Specify each system property according to the coding rules described in Rules for coding JVM profiles and JVM properties files. 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.
Property values are passed to the JVM for the construction of system properties as if specified by a -D option in a java command. For example, the JVM properties file could set the java.security.policy property by specifying:
java.security.policy=
file:/usr/lpp/cicsts/cicsts31/lib/security/dfjejbpl.policy
(where cicsts31 is a user-defined value that you specify during the installation of CICS TS). CICS uses this information to create a Java launcher option as follows:
-Djava.security.policy=
file:/usr/lpp/cicsts/cicsts31/lib/security/dfjejbpl.policy
As described in Options in JVM profiles, if you specify CLASSCACHE=YES in a JVM profile, making the JVM a worker JVM that uses the shared class cache, certain system properties in the JVM properties file referenced by the JVMPROPS option on the JVM profile are treated differently. The affected system properties are ibm.jvm.shareable.application.class.path and java.compiler. The descriptions for these system properties tell you how to handle them for worker JVMs.
As described in Options in JVM profiles, the master JVM that initializes the shared class cache is not used to run Java applications. Because of this, most of the system properties that would normally be specified for a JVM are not needed 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.
In the JVM properties file for the master JVM, the only system property that needs to be specified is ibm.jvm.shareable.application.class.path, which should specify the paths to the shareable application classes for all the applications that will run in worker JVMs that use the shared class cache.
The java.compiler system property can be included in the JVM properties file for the master JVM, or allowed to default to jitc. Also, if you want to activate tracing for the master JVM, you can specify the ibm.dg.trc.external system property, which should only be used with care. These system properties are not specified in the CICS-supplied sample JVM properties file dfjjvmcc.props.
The remaining system properties, other than those that are set automatically by the IBM JVM, are irrelevant for a master JVM. They do not cause an error if they are specified in the JVM properties file for the master JVM, but you should not include any of them unless you do so under the direction of Level 2 support.
As described in Options in JVM profiles, the JVM profile DFHJVMCD, and its associated JVM properties file, dfjjvmcd.props, are 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).
Only make the changes to dfjjvmcd.props that are necessary to run applications, as follows:
Do not make any other changes to dfjjvmcd.props.
You should ensure that the JVM properties files are secure, with update authority restricted to system administrators. This is because the JVM properties files are typically used to define sensitive JVM configuration options, such as the security policy file and the trusted middleware class path.
In particular, if you specify that a secure LDAP server is to be used, by coding java.naming.security.authentication in the JVM properties files, you also need to specify java.naming.security.principal and java.naming.security.credentials. These properties hold the UserID and password that CICS requires to access the secure LDAP service, so you need to give particular attention to the access controls in force at your installation for the JVM properties files, and any other copies of this information that you have.
The standard Java system properties, common to all JVMs, are as follows:
This system property can be specified in the JVM properties file for a master JVM.
In JVM properties files referenced by JVM profiles where you have specified CLASSCACHE=YES (that is, the JVM properties files for worker JVMs), this system property must either:
The activities of the Java just-in-time (JIT) compiler can interfere with the logging of unresettable events, reset trace events and cross-heap events. During the development process, specify java.compiler=NONE to turn off the JIT compiler for the JVM. Remember to turn the JIT compiler back on when you have finished investigating unresettable events, reset trace events and cross-heap events in your application.
If you do use the java.naming.provider.url property, this sets the protocol, host name, and port number of the COS Naming Service that CICS is to use. For example,
java.naming.provider.url=IIOP://servername.hursley.ibm.com:900
For special considerations that apply if you are using the COS Naming Directory Server supplied with WebSphere Application Server Version 5 or later, see com.ibm.cics.ejs.nameserver.
You are strongly recommended to avoid using both the java.naming.provider.url and the com.ibm.cics.ejs.nameserver property in the same JVM properties file, because:
CICS needs to have write access into the LDAP namespace. If the LDAP service is set up securely, these three properties--authentication, credentials and principal--are required. If the LDAP service is set up so that any user can write to it, these three are not needed. Your LDAP administrator can tell you whether or not you need to include these properties in your JVM properties file.
Simple is the only value for this property that is supported by CICS. Specifying java.naming.security.authentication=simple indicates that the LDAP name server is running in secure mode.
If you do specify this property, you have also to specify java.naming.security.principal and java.naming.security.credentials.
Because these properties specify the user ID and password that CICS requires to access the secure LDAP service, you need to give particular attention to the file permissions controlling access to the JVM properties file and any other copies of this information that you have.
This property is required if you specified java.naming.security.authentication=simple. Your LDAP administrator provides the value that you should specify, for example, java.naming.security.credentials=secret.
This property is required if you specified java.naming.security.authentication=simple. Your LDAP administrator provides the value that you should specify, for example, java.naming.security.principal=cn=CICSUser,c=uk .
java.security.manager=default
or
java.security.manager=""
or
java.security.manager=
All these statements have the effect of enabling the default security
manager. If you do not include the java.security.manager system
property in your JVM properties file, then the JVM runs without Java 2
security enabled. If you need to disable Java 2 security for a JVM, comment out
this system property.
To enable CICS Java applications and enterprise beans to run successfully when Java 2 security is active, you need to specify, as a minimum, an additional policy file that gives CICS the permissions it needs to run the enterprise beans container, and gives applications the permissions outlined in the Enterprise JavaBeans specification, Version 1. The CICS-supplied enterprise beans policy file, dfjejbpl.policy, contains the permissions that you need for this purpose. To specify this policy file, include the system property:
java.security.policy=/usr/lpp/cicsts/cicsts31/lib/security/dfjejbpl.policy
where cicsts31 is your chosen value for the USSDIR installation parameter that you defined when you installed CICS TS.
"Managing security for enterprise beans" in Java Applications in CICS has more information about specifying security policy files, and about dfjejbpl.policy.
To specify the DB2-supplied JDBC drivers, set the system property as:
jdbc.drivers=COM.ibm.db2os390.sqlj.jdbc.DB2SQLJDriver
This is a common name that works for all levels of JDBC driver supplied by DB2®, including the DB2 Universal JDBC Driver.
"Using JDBC and SQLJ to access DB2 data from Java programs and enterprise beans written for CICS" in the CICS DB2 Guide has more information about using JDBC.
In addition to the basic system properties, shown in Standard system properties, which are common to all JVMs, there are some that are unique to the IBM persistent reusable JVM. These are listed below.
com.ibm.cics.ejs.nameserver=ldap://myldserv.hursley.ibm.com:389
where myldserv.hursley.ibm.com is the URL of the name server
and 389 is the port number on which it is configured to listen.
Your LDAP administrator can supply the correct URL and port number.com.ibm.cics.ejs.nameserver=iiop://mycsserv.hursley.ibm.com:900
The relevant administrator in your organisation can supply the correct
name and port number.
If you are using the COS Naming Directory Server supplied with WebSphere Application Server Version 5 or later, you should specify:
com.ibm.cics.ejs.nameserver=iiop://mycsserv.hursley.ibm.com:2809/domain/legacyRoot
This is because, in WebSphere Application Server:
com.ibm.cics.ejs.loadjndiproperties=true
Place
the directory containing the jndi.properties file on either the
shareable application class path (in the JVM properties file) or the trusted
middleware class path (in the JVM profile), in all the relevant JVM profiles
or JVM properties files, for all the regions that you want to share the same
nameserver settings.
See also the com.ibm.websphere.naming.jndicache.cacheobject property.
com.ibm.ws.naming.ldap.containerdn=ibm-wsnTree=t1,o=WASNaming,c=us
An example of this statement is included in the CICS-supplied sample
JVM properties file, dfjjvmpr.props. Your LDAP administrator can
supply the correct value for your installation.
The Container Distinguished Name is the root of the system name space.
This property is not required if you specify a COS naming service.
com.ibm.ws.naming.ldap.noderootrdn=ibm-wsnName=legacyroot,
ibm-wsnName=PLEX2,ibm-wsnName=domainRoots
Your LDAP administrator can
supply the correct value.
An example of this statement is included in the CICS-supplied sample JVM properties file, dfjjvmpr.props.
This property is not required if you specify a COS naming service.
This system property can be specified in the JVM properties file for a master JVM.
When CICS starts to use or re-use a JVM, it ensures that any trace options that you have set and activated using CETR are applied. Activating or deactivating a trace option using CETR overrides any setting for that trace option in the ibm.dg.trc.external system property. For example, a trace option that is activated in the system property, but deactivated using CETR, will be deactivated when CICS starts to use or re-use the JVM. If you use CETR to activate any trace options that are not referred to in the ibm.dg.trc.external system property, the trace options that you have specified in CETR are added to any trace options that you have set using the ibm.dg.trc.external system property. The trace output will then reflect all the trace options that you requested in both CETR and the system property.
When you activate JVM trace, the JVM trace appears as CICS trace point SJ 4D01. If the JVM trace facility fails, CICS issues the trace point SJ 4D00.
This system property is not set in the CICS-supplied JVM properties files, so by default the function is not enabled. Note that when you include this system property in the JVM properties file with any value ("on" is one possibility), the function is enabled. To disable the function, you need to comment out or remove the system property; there is no value you can specify for the system property that disables the function.
Cross-heap references are references between the middleware heap and the transient heap in the JVM. When you set up the JVM as described here, cross-heap references are logged to the event output destination at the time that each reference is created. The log entry includes a full stack trace to identify the line of code that created the cross-heap reference.
Most of the cross-heap references that are logged will be removed before the JVM is reset, through the normal actions of the CICS and JVM code, and through any actions that your application takes for this purpose. However, if any cross-heap references are not removed before the JVM is reset, they cause the JVM to perform a trace-for-unresettability check. Any references that are found to be in live objects trigger unresettable events, which cause the JVM to be marked as unresettable and destroyed. Any references that are found to be in unreferenced middleware heap objects (garbage) are reported as reset trace events, which do not cause the JVM to be destroyed, but have still wasted processor time by causing the trace-for-unresettability check. You should therefore ensure that all cross-heap references created by your applications are removed from the JVM before it is reset.
You can use the memory location listed for an unresettable event or a reset trace event to identify the cross-heap reference recorded in the event log which is responsible for triggering the event. You can then use the stack trace associated with the cross-heap reference to help you to fix the problem. You might have to perform compensatory actions in application code to cause a cross-heap reference to be removed, which could include closing files or streams, emptying collections, or other kinds of clean-up activity. If you cannot remove the cross-heap reference in application code, consider contacting your IBM support representative for further advice.
The activities of the Java just-in-time (JIT) compiler can interfere with the logging of cross-heap references. During the development process, specify the system property java.compiler=NONE in the JVM properties file to turn off the JIT compiler for the JVM. (The word NONE must be in upper case.) When you have finished investigating cross-heap references in your application, remember to turn the JIT compiler back on.
ibm.jvm.events.output=event.log
which
creates a file called event.log in the directory specified by the
WORK_DIR option.
If you use this system property to name a specific HFS file as the destination for the unresettable events information, then the information goes to that file, and is not intercepted by any class named on the USEROUTPUTCLASS option in the JVM profile. If the system property names the destination as stdout or stderr, then the information is intercepted by any class named on the USEROUTPUTCLASS option. If the system property is null, then this output is not produced at all.
This system property is not set in the CICS-supplied JVM properties files, so by default the function is not enabled. Note that when you include this system property in the JVM properties file with any value ("on" is one possibility), the function is enabled. To disable the function, you need to comment out or remove the system property; there is no value you can specify for the system property that disables the function.
This system property is not set in the CICS-supplied JVM properties files, so by default the function is not enabled. Note that when you include this system property in the JVM properties file with any value ("on" is one possibility), the function is enabled. To disable the function, you need to comment out or remove the system property; there is no value you can specify for the system property that disables the function.
Reset trace events are caused by cross-heap references that are still present in out-of-scope JVM objects (garbage) in the JVM at reset time. (If the cross-heap reference is still in scope, it causes an unresettable event.) Reset trace events do not cause the JVM to be marked as unresettable and destroyed, but you should still eliminate the cross-heap references that caused them, because the trace-for-unresettability check that is required for these cross-heap references reduces the performance of the JVM. Specify the ibm.jvm.crossheap.events system property to log the lines of code in an application that are responsible for cross-heap references.
The activities of the Java just-in-time (JIT) compiler can interfere with the logging of reset trace events. During the development process, specify the system property java.compiler=NONE in the JVM properties file to turn off the JIT compiler for the JVM. (The word NONE must be in upper case.) Remember to turn the JIT compiler back on when you have finished investigating reset trace events in your application.
For worker JVMs (those with CLASSCACHE=YES in their JVM profile), the shareable application class path is taken from the JVM properties file for the master JVM that initializes the shared class cache. If it is specified in the JVM properties file for a worker JVM, it is ignored. To specify the directory paths for application classes that run in a worker JVM, use the ibm.jvm.shareable.application.class.path system property in the JVM properties file 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.
ibm.jvm.unresettable.events.level=max
A frequent cause of an unresettable event is that the Java program that just ran in the JVM has performed an unresettable action. An unresettable action is when a program uses Java interfaces that modify the state of a JVM in a way that cannot be properly reset, such as changing system properties or loading a native library. The document Persistent Reusable Java Virtual Machine User's Guide, SC34-6201, has more information about these unresettable actions. If one or more such actions are detected during the execution of a user's Java program, the JVM is marked unresettable, and CICS destroys the JVM when the Java program has finished using it. Another possible cause of an unresettable event is if a cross-heap reference in the JVM has been found, in the course of a trace-for-unresettability check, to be still in scope (rather than in garbage). Unresettable events can also occur if there is an error in the JVM code.
The activities of the Java just-in-time (JIT) compiler can interfere with the logging of unresettable events. During the development process, specify the system property java.compiler=NONE in the JVM properties file to turn off the JIT compiler for the JVM. (The word NONE must be in upper case.) Remember to turn the JIT compiler back on when you have finished investigating unresettable events in your application.
The CICS-supplied JVM properties files also specify some special system properties that are required only for tracing in the CICS Connector for CICS TS. The CICS Connector for CICS TS allows a Java program or enterprise bean running on CICS TS to link to a CICS server program, and uses the CICS Transaction Gateway (CTG) code. These CTG trace system properties are:
gateway.T=off
gateway.T.entry=off
gateway.T.lines=off
gateway.T.exit=off
gateway.T.stack=off
gateway.T.trace=off
gateway.T.timing=off
For more information about these CTG system properties, see Java Applications in CICS.