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
- 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 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.
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.cmci.user.agent.allow.list={file_path}
-
Note: This property is intended only for the CMCI JVM server.
Specifies the location of the client allowlist file and enables allowlist processing in the CMCI JVM server.
- com.ibm.cics.jvmserver.cmci.user.agent.allow.list.monitor.interval={time|10s}
-
Note: This property is intended only for the CMCI JVM server.
Specifies the interval of Liberty cache file monitoring checks performed by the CMCI JVM server to refresh the cache of user-agent allowlist values obtained from the client allowlist file.
- com.ibm.cics.jvmserver.cmci.user.agent.allow.list.reject.text={text}
-
Note: This property is intended only for the CMCI JVM server.
Specifies a custom response message to return to the user when a request to connect to the CMCI is rejected because the system management client being used is not in the client allowlist.
- com.ibm.cics.jvmserver.controller.timeout={time|90000ms}
-
This value should be greater than the Liberty bundlepart timeout value, otherwise bundleparts can incorrectly timeout. Only use numerical characters when changing this value.
- 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.
- 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.
- 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.
- 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.
- com.ibm.cics.jvmserver.wlp.autoconfigure={false|true}
- Specifies whether CICS creates the necessary Liberty directories, server.xml and other configuration files within WLP_USER_DIR if they do not already exist.
- com.ibm.cics.jvmserver.wlp.bundlepart.timeout={time|60000ms}
- Controls the timeout value used by CICS Liberty during bundlepart installation. If the operation
times out, the bundlepart - and by association, the bundle - is moved to the disabled state.
When Liberty acknowledges the install phase, the bundlepart stays in an enabling state until Liberty has fully started the application. The timeout does not affect bundleparts that have reached this state. Only use numerical characters when changing this value.
Important: This value should be greater than the Liberty configuration monitor interval, otherwise bundleparts can incorrectly timeout. - 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={false|true}
-
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.security.subject.create={true|false}
- Allows the user to turn off Java
Subject creation when performing a
LINK
to Liberty. - 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.keystore.location={zFS|location_url}
- CICS generates a default Liberty keystore element with the ID of
defaultKeyStore. The location of the default keystore is in zFS for Liberty and
in SAF for CMCI. Use this property to explicitly request either a zFS based keystore, a SAF-based
keystore, and to override the user ID and key ring values.
- zFS
- Specifies that Liberty creates the default zFS based Java keystore. zFS is the default except for the CMCI JVM server, which updates the zFS keystore location to SAF.
- location_url
-
A SAF-based keystore is configured by using a location_url value with the following format.
scheme://userid/keyring
The scheme can be one of the following values: safkeyring, safkeyringhw, or safkeyringhybrid. For more information about SAF key ring formats, see the System Authorization Facility (SAF) security guide in the IBM Semeru Runtime Certified Edition for z/OS documentation.
Examples:safkeyring:///KEYRING.CICS1
specifies that CICS accesses the RACF key ring KEYRING.CICS1 by using the CICS region user ID.safkeyring://USER1/KEYRING.CICS1
specifies that CICS accesses the RACF key ring KEYRING.CICS1 by using the user ID USER1.safkeyring
orsafkeyring:///
specifies that the values from KEYRING SIT parameter are used to create the keystore.
Java 11 Use safkeyringjce, safkeyringjcecca, or safkeyringjcehybrid for the scheme when running Java 11.
This property is used only when com.ibm.cics.jvmserver.wlp.autoconfigure=true.
- com.ibm.cics.jvmserver.wlp.server.keystore.type=keystore_type
-
This property overrides the keystore type that is configured by CICS. By default, the keystore type is inferred from the com.ibm.cics.jvmserver.wlp.server.keystore.location property and only needs to be configured if you don't want to accept the default.
Some examples of valid keystore types are JCERACFKS, JCECCARACFKS, JCEHYBRIDRACFKS, or PKCS12.
For more information about keystore types, see Keystores in the IBM WebSphere® Application Server for z/OS Liberty documentation.
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.jvmserver.wlp.wab={false|true}
-
Controls the Liberty feature
wab-1.0
in server.xml. If you want to use Java EE 8 in standard or integrated-mode Liberty, you must set this option tocom.ibm.cics.jvmserver.wlp.wab=false
, and then add the required Java EE 8 features.If you want to use EBA files then you must set this option to
com.ibm.cics.jvmserver.wlp.wab=true
. - com.ibm.cics.jvmserver.wlp.xml.format={false|true}
-
Enables CICS to format the white space in server.xml for improved readability.
- 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/J8.0_64/lib/security/java.policy
, where thejava/J8.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={false|true}
- 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).