JVM system properties

JVM system properties provide configuration information specific to the JVM and its runtime environment. You provide JVM system properties by adding them to the JVM profile. At run time, CICS® reads the properties from the JVM profile, and passes them to the JVM.

Property prefix

System properties must be set by using a -D prefix, for example the correct syntax for com.ibm.cics is -Dcom.ibm.cics.
  • com.ibm.cics indicates that the property is specific to the IBM® JVM in a CICS environment.
  • com.ibm indicates a general JVM property that is used more widely.
  • java.ibm also indicates a general JVM property that is used more widely.

For information about general properties, see JVM profile validation and properties.

Property coding rules

Properties must be specified according to a set of coding rules. For more information about the rules, see Rules for coding JVM profiles.

Applicability of properties to different uses of JVM server

The three types of JVM server are OSGi, Liberty, and Classpath. Classpath JVM servers can be further refined to Axis2 capable, Security Token Server (STS) capable, Batch capable, and Mobile capable. The following table shows the options that apply to each specific capability. The table also indicates whether or not a property is supported for a particular use of a JVM server. Be aware that some properties are read-only. Changing a read-only property might result in runtime environment failure. For details about these properties, see Read-only properties.

Table 1. Options by JVM server use
System property OSGi Liberty Classpath
com.ibm.cics.json.enableAxis2Handlers Not supported Not supported Supported
com.ibm.cics.jvmserver.applid Supported Supported Supported
com.ibm.cics.jvmserver.cics.product.name Not supported Supported Not supported
com.ibm.cics.jvmserver.cics.product.version Not supported Supported Not supported
com.ibm.cics.jvmserver.configroot Supported Supported Supported
com.ibm.cics.jvmserver.controller.timeout Supported Supported Not supported
com.ibm.cics.jvmserver.local.ccsid Supported Supported Supported
com.ibm.cics.jvmserver.name Supported Supported Supported
com.ibm.cics.jvmserver.override.ccsid Supported Supported Supported
com.ibm.cics.jvmserver.supplied.ccsid Supported Supported Supported
com.ibm.cics.jvmserver.threadjoin.timeout Supported Supported Not supported
com.ibm.cics.jvmserver.trace.filename Supported Supported Supported
com.ibm.cics.jvmserver.trace.format Supported Supported Supported
com.ibm.cics.jvmserver.trace.specification Supported Supported Supported
com.ibm.cics.jvmserver.trigger.timeout Supported Supported Not supported
com.ibm.cics.jvmserver.unclassified.tranid Supported Supported Not supported
com.ibm.cics.jvmserver.unclassified.userid Supported Supported Not supported
com.ibm.cics.jvmserver.wlp.args Not supported Supported Not supported
com.ibm.cics.jvmserver.wlp.autoconfigure Not supported Supported Not supported
com.ibm.cics.jvmserver.wlp.defaultapp Not supported Supported Not supported
com.ibm.cics.jvmserver.wlp.install.dir Not supported Supported Not supported
com.ibm.cics.jvmserver.wlp.jdbc.driver.location Not supported Supported Not supported
com.ibm.cics.jvmserver.wlp.jta.integration Not supported Supported Not supported
com.ibm.cics.jvmserver.wlp.latebinding Not supported Supported Not supported
com.ibm.cics.jvmserver.wlp.optimize.static.resources Not supported Supported Not supported
com.ibm.cics.jvmserver.wlp.optimize.static.resources.extra Not supported Supported Not supported
com.ibm.cics.jvmserver.wlp.reserve.thread.percentage Not supported Supported Not supported
com.ibm.cics.jvmserver.wlp.server.config.dir Not supported Supported Not supported
com.ibm.cics.jvmserver.wlp.server.host Not supported Supported Not supported
com.ibm.cics.jvmserver.wlp.server.http.port Not supported Supported Not supported
com.ibm.cics.jvmserver.wlp.server.https.port Not supported Supported Not supported
com.ibm.cics.jvmserver.wlp.server.name Not supported Supported Not supported
com.ibm.cics.jvmserver.wlp.server.output.dir Not supported Supported Not supported
com.ibm.cics.sts.config Not supported Not supported Supported (STS only)
com.ibm.ws.logging.console.log.level Not supported Supported Not supported
com.ibm.ws.zos.core.angelName Not supported Supported Not supported
com.ibm.ws.zos.core.angelRequired Not supported Supported Not supported
console.encoding Supported Supported Supported
file.encoding Supported Supported Supported
java.security.manager Supported Not supported Supported
java.security.policy Supported Not supported Supported
org.osgi.framework.storage.clean Supported Supported Not supported
org.osgi.framework.system.packages.extra Supported Supported Not supported
osgi.compatibility.bootdelegation Supported Supported Not supported

Read-only properties

com.ibm.cics.json.enableAxis2Handlers
Indicates that a JVM requires the ability to run Axis2 handler programs when processing JSON data. This property is only relevant to a JVM that has JAVA_PIPELINE=YES specified and is configured to support JSON pipelines. This option is not relevant to z/OS Connect in CICS, and should only be enabled if the capability is required. Enabling this option will ensure that Axis2 Handler programs can run during a JSON workload, but there is likely to be a performance penalty in enabling this option, and some of the capabilities of mapping level 4.2 and later WSBind files will not be available for use.
com.ibm.cics.jvmserver.applid
Specifies the CICS region application identifier (APPLID). This is a read-only property. You can use this property in an application but you should not change it.
com.ibm.cics.jvmserver.cics.product.name
Specifies the name of the CICS product under which Liberty is running. This is a read-only property. You can use this property in an application but you should not change it.
com.ibm.cics.jvmserver.cics.product.version
Specifies the version of the CICS product under which Liberty is running. This is a read-only property. You can use this property in an application but you should not change it.
com.ibm.cics.jvmserver.configroot
Specifies the location where configuration files, such as the JVM profile of a JVM server, can be found. This is a read-only property. You can use this property in an application but you should not change it.
com.ibm.cics.jvmserver.local.ccsid
Specifies the code page for file encoding when the JCICS API is used. This is a read-only property. You can use this property in an application but you should not change it.
com.ibm.cics.jvmserver.name
Specifies the name of the JVM server. This is a read-only property. You can use this property in an application but you should not change it.
com.ibm.cics.jvmserver.supplied.ccsid
Specifies the default CCSID for the local CICS region. This is a read-only property. You can use this property in an application but you should not change it.
com.ibm.cics.jvmserver.trace.filename
Specifies the name of the JVM server trace file. This is a read-only property. You can use this property in an application but you should not change it.
com.ibm.cics.jvmserver.wlp.install.dir
Specifies the location of the Liberty installation. This is a read-only property. You can use this property in an application but you should not change it.
com.ibm.cics.jvmserver.wlp.server.config.dir
Specifies the location of the Liberty configuration directory. This is a read-only property. You can use this property in an application but you should not change it.
com.ibm.cics.jvmserver.wlp.server.output.dir
Specifies the location of the Liberty output directory where you can find Liberty logs. This is a read-only property. You can use this property in an application but you should not change it.

Properties that can be changed

com.ibm.cics.jvmserver.controller.timeout={time|90000ms}
Only use numerical characters when changing this value.
Warning: This property is subject to change at any time.
com.ibm.cics.jvmserver.override.ccsid=
Warning: This property is intended for advanced users.
It overrides the code page for file encoding when the JCICS API is used. By default, JCICS uses the value of the LOCALCCSID system initialization parameter as the file encoding. If you choose to override this value, set the code page in this property. Use an EBCDIC code page. You must ensure that your applications are consistent with the new code page, or errors might occur. For more information about valid CCSIDs, see LOCALCCSID system initialization parameter.
com.ibm.cics.jvmserver.threadjoin.timeout={time|30000ms}
Controls the timeout value when requests that are waiting for threads are queuing for service.Only use numerical characters when changing this value.
com.ibm.cics.jvmserver.trace.format={FULL|SHORT|ABBREV}
Controls the format of the trace which can be varied for your own purposes. You must set it to SHORT when you send diagnostic information to IBM service.
com.ibm.cics.jvmserver.trace.specification={filter_text}
Warning: Use this property only under IBM service guidance. This property is subject to change at any time.

Specifies a JVM server trace filter string allowing finer grained control over package and class trace from the JVM server. {filter_text} is a colon separated string of clauses that sets the trace level of one or more specified components. If not specified, the default value is equivalent to com.ibm.cics.*=ALL.

The SJ domain trace flag remains the main switch, but this trace specification allows for additional filtering of specific components.

For any given class or package, the most specific filter clause applies. Each filter clause can be set to one of the following levels:

{ALL, DEBUG, ENTRYEXIT, EVENT, INFO, WARNING, ERROR, NONE}

Example 1:

com.ibm.cics.jvmserver.trace.specification=com.ibm.cics.*=NONE

A single filter clause that suppresses all output.

Example 2:

com.ibm.cics.jvmserver.trace.specification=com.ibm.cics.*=NONE:com.ibm.cics.wlp.*=ALL

This example has two filter clauses. The first filter clause suppresses all trace. The second filter clause is more specific for all packages under the com.ibm.cics.wlp component and ensures all of their trace output is written.

Example 3:

com.ibm.cics.jvmserver.trace.specification=com.ibm.cics.wlp.impl.CICSTaskWrapper=NONE:com.ibm.cics.wlp.impl.CICSTaskInterceptor=NONE 

This example has two filter clauses. All trace is written, except trace that is produced from the specific CICSTaskWrapper and CICSTaskInterceptor classes of the com.ibm.cics.wlp.impl package.

com.ibm.cics.jvmserver.trigger.timeout={time|500ms}
Only use numerical characters when changing this value.
Warning: Use this property only under IBM service guidance. This property is subject to change at any time.
com.ibm.cics.jvmserver.unclassified.tranid={transaction id}
Specifies the default transaction that is used for unclassified work that is run in a JVM server.
  • In a Liberty JVM server, unclassified work runs under transaction CJSU, unless you specify the com.ibm.cics.jvmserver.unclassified.tranid property.
  • In an OSGI JVM server, unclassified work runs under transaction CJSA, unless you specify the com.ibm.cics.jvmserver.unclassified.tranid property.
The user must ensure that the transaction ID specified is defined to CICS, by duplicating the CJSA or CJSU transaction.
com.ibm.cics.jvmserver.unclassified.userid={user id}
Allows users to change the default user ID under which unclassified work is run as a CICS task in a JVM server. If not specified, the CICS default user ID is used. The user ID specified must be defined to RACF®® and have the necessary permissions to run the work.
Unclassified work is any request not identified by the HTTP classification component of Liberty, for example JMS, inbound JCA, EJB requests and so on.
com.ibm.cics.jvmserver.wlp.args=

Provides a way to set Liberty server options during start-up. For a list of server options, see the 'options' section in Server command options.

Warning: This property is typically used under IBM service guidance.
com.ibm.cics.jvmserver.wlp.autoconfigure={false|true}
Specifies whether CICS automatically creates and updates the server.xml file for the Liberty JVM server. If you set this property to true, CICS creates the necessary Liberty directory structure and configuration files. CICS also updates the server.xml file if you provide values for other Java™ properties, such as an HTTP port number.
com.ibm.cics.jvmserver.wlp.defaultapp={false|true}
Instructs CICS to add the defaultApp-1.0 feature to server.xml, which installs the default CICS web application that can be used to verify that the Liberty server has installed and started correctly.
Tip: This property is used only when com.ibm.cics.jvmserver.wlp.autoconfigure=true.
com.ibm.cics.jvmserver.wlp.jdbc.driver.location=
Specifies the location of the directory that contains the DB2® JDBC drivers. The location must contain the DB2 JDBC driver classes and lib directories. If the autoconfigure property com.ibm.cics.jvmserver.wlp.autoconfigure=true, when the JVM server is enabled, the existing example configuration in server.xml is replaced with the default configuration and any user updates are lost.
com.ibm.cics.jvmserver.wlp.jta.integration={false|true}
Enables CICS integration with the Java Transaction API (JTA). When transactions that are created through the JTA interface are in effect, the CICS unit of work is subordinate to the Java Transaction Manager.
Tip: This property is used only when com.ibm.cics.jvmserver.wlp.autoconfigure=true.
com.ibm.cics.jvmserver.wlp.latebinding={NONHTTP|COMPATIBILITY}
Warning: Use this property only under IBM service guidance. This property is subject to change at any time.
com.ibm.cics.jvmserver.wlp.optimize.static.resources={true|false}

Enables requests for static content to be processed on a non-CICS thread. The following types of file are recognized as static: .css .gif .ico .jpg .jpeg .js and .png.

com.ibm.cics.jvmserver.wlp.reserve.thread.percentage={percent|10}

Reserves a percentage of the threadlimit of the Liberty JVM server for use by OSGi Applications. The value can be between 1% and 50%.

com.ibm.cics.jvmserver.wlp.optimize.static.resources.extra=

Specifies a custom list of extra static resources for optimization. Items must be comma-separated, and begin with a period, for example: .css, .gif, .ico.

Tip: This value is only respected when com.ibm.cics.jvmserver.wlp.optimize.static.resources=true.
com.ibm.cics.jvmserver.wlp.server.host={*|hostname|IP_address}
Specifies the name or IP address in IPv4 or IPv6 format of the host for HTTP requests to access the web application. The Liberty JVM server uses * as the default value. This value is not appropriate for running a web application in CICS, so either use this property to provide a different value or update the server.xml file.
Tip: This property is used only when com.ibm.cics.jvmserver.wlp.autoconfigure=true.
com.ibm.cics.jvmserver.wlp.server.http.port={9080|port_number}
Specifies a port to accept HTTP requests for a Java web application. CICS uses the default value that is supplied by Liberty. The Liberty JVM server does not use a TCPIPSERVICE resource. Ensure that the port number is free or shared on the z/OS® system.
Tip: This property is used only when com.ibm.cics.jvmserver.wlp.autoconfigure=true.
com.ibm.cics.jvmserver.wlp.server.https.port={9443|port_number}
Specifies a port to accept HTTPS requests for a Java web application. CICS uses the default value that is supplied by Liberty. The Liberty JVM server does not use a TCPIPSERVICE resource, so ensure that the port number is free or shared on the z/OS system.
Tip: This property is used only when com.ibm.cics.jvmserver.wlp.autoconfigure=true.
com.ibm.cics.jvmserver.wlp.server.name={defaultServer|server_name}
Specifies the name of the Liberty server. You should not need to specify this property as it affects the location of the Liberty server configuration and output files and directories.
com.ibm.cics.sts.config=path
Specifies the location and name of the STS configuration file.
com.ibm.ws.logging.console.log.level={INFO|AUDIT|WARNING|ERROR|OFF}
Controls which messages Liberty writes to the JVM server stdout file. Liberty console messages are also written to the Liberty messages.log file independent of the setting of this property.
com.ibm.ws.zos.core.angelName=named_angel
Specifies a named angel process for the Liberty JVM server to connect to. If you do not specify com.ibm.ws.zos.core.angelName, when required, the default angel process is used for Liberty JVM server startup.
com.ibm.ws.zos.core.angelRequired={false|true}
Indicates whether an angel process is required for Liberty JVM server startup.
console.encoding=
Specifies the encoding for JVM server output files.
file.encoding=
Specifies the code page for reading and writing characters by the JVM. By default, a JVM on z/OS uses the EBCDIC code page IBM1047 (or cp1047).
  • In a profile that is configured for OSGi, you can specify any code page that is supported by the JVM. CICS tolerates any code page because JCICS uses the local CCSID of the CICS region for its character encoding.
  • In a profile that is configured for the Liberty JVM server, the supplied default value is ISO-8859-1. You can also use UTF-8. Any other code page is not supported.
  • In a profile that is configured for Axis2, you must specify an EBCDIC code page.
java.security.manager={default| "" | |other_security_manager}
Specifies the Java security manager to be enabled for the JVM. To enable the default Java security manager, include this system property in one of the following formats:
  • java.security.manager=default
  • java.security.manager=""
  • java.security.manager=

All these statements enable the default security manager. If you do not include the java.security.manager system property in your JVM profile, the JVM runs with Java security disabled.

java.security.policy=
Describes the location of extra policy files that you want the security manager to use to determine the security policy for the JVM. A default policy file is provided with the JVM in /usr/lpp/java/J7.0_64/lib/security/java.policy, where the java/J7.0_64 subdirectory names are the default values when you install the IBM 64-bit SDK for z/OS, Java Technology Edition. The default security manager always uses this default policy file to determine the security policy for the JVM, and you can use the java.security.policy system property to specify any policy files that you want the security manager to take into account, in addition to the default policy file.

To enable CICS Java applications to run successfully when Java security is active, specify, as a minimum, an extra policy file that gives CICS the permissions it requires to run the application.

For information about enabling Java security, see Enabling a Java security manager.

org.osgi.framework.storage.clean={onFirstInit}
This option is specific to OSGi-enabled JVM servers, including Liberty. It specifies if and when the storage area for the OSGi framework should be cleaned. If no value is specified, the framework storage area will not be cleaned. onFirstInit flushes the bundle cache when the framework instance is first initialized. i.e when the JVM server is enabled. Framework storage cleaning is not necessary under normal operations.
org.osgi.framework.system.packages.extra=
This option is specific to OSGi-enabled JVM servers, including Liberty, which allows extensions of the JRE and custom Java packages to be exposed through the OSGi framework for subsequent bundle import resolution. JVM vendors might provide different extensions in the JRE. In an IBM JVM server, the option is augmented to include the set of packages which CICS chooses to expose from the IBM JRE. You can set this property to define additional packages, if required. For further information, see OSGi Alliance Specifications.
osgi.compatibility.bootdelegation={true|false}
This option is specific to the Equinox implementation of OSGi. It applies to OSGi-enabled JVM servers, including Liberty. When set to true, the OSGi framework employs a last resort bootdelegation strategy for packages that are not found through the normal OSGi bundle dependency resolution mechanism. This option allows the OSGi run time to be more tolerant if explicit dependencies were overlooked at development time. As a last resort algorithm, a small amount of overhead is incurred compared to direct resolution (where the package is explicitly listed in the Import-Package bundle header).
For strict OSGi compliance, increased portability, and optimum performance, set this option to false and ensure all the packages that are used in your OSGi bundles are explicitly declared in the bundle MANFEST.MF.