Configuring a Liberty JVM server

Configure the Liberty JVM server if you want to deploy Java™ web applications such as JSP, JSF and Servlets.

1. Create a JVMSERVER resource. If you want to create a JVMSERVER resource within a CICS bundle, see Artifacts that can be deployed in bundles.
   1. Specify a name for the JVM profile for the JVM server.
      On the JVMPROFILE attribute of JVMSERVER, specify a 1 - 8 character name. This name is used for the prefix of the JVM profile, which is the file that holds the configuration options for the JVM server. You do not need to specify the suffix, .jvmprofile, here.
   2. Specify the thread limit for the JVM server.
      On the THREADLIMIT attribute of the JVMSERVER, specify the maximum number of threads you want to allocate. The Liberty JVM server will set a minimum of five threads. The actual number of threads used depends on the workload that you run in the JVM server. To start with, you can accept the default value and tune the environment later. You can set up to 256 threads in a JVM server.
2. Create the JVM profile to define the configuration options for the JVM server.
   You can use the sample profile, DFHWLP.jvmprofile, as a basis. This profile contains a subset of options that are suitable for starting the JVM server. All options and values for the JVM profile are described in JVM profile validation and properties. Follow the coding rules, including those for the profile name, in Rules for coding JVM profiles.
   1. Set the location for the JVM profile.
      The JVM profile must be in the directory that you specify on the system initialization parameter, JVMPROFILEDIR. For more information, see Setting the location for the JVM profiles.
   2. Make the following changes to the sample profile:
      • Set JAVA_HOME to the location of your installed IBM® Java SDK.
      • Set WORK_DIR to your choice of destination directory for messages, trace, and output from the JVM server.
      • Set WLP_INSTALL_DIR to &USSHOME;/wlp.
      • Set TZ to specify the timezone for time stamps on messages from the JVM server. An example for the United Kingdom is TZ=GMT0BST,M3.5.0,M10.4.0.
   3. Save your changes to the JVM profile.
      The JVM profile must be saved in EBCDIC file encoding on UNIX System Services and the file suffix must be .jvmprofile.
3. Create the Liberty server configuration. When using autoconfigure this is performed at JVM server setup. To enable Liberty JVM server autoconfiguration, you set the following JVM system properties in the JVM profile.
   1. Enable autoconfigure by setting -Dcom.ibm.cics.jvmserver.wlp.autoconfigure=true.
   2. Set the HTTP server listener port by using -Dcom.ibm.cics.jvmserver.wlp.server.http.port.
   3. Set the host that the Liberty HTTP server listens on, using -Dcom.ibm.cics.jvmserver.wlp.server.host.
   4. Set the Liberty server name by using -Dcom.ibm.cics.jvmserver.wlp.server.name.

   Alternatively you can configure the Liberty directory structure and the server.xml configuration file manually. This is the default setting, and is appropriate when the configuration files need to be carefully controlled. For more information, see Creating a configuration directory structure and Manually tailoring server.xml. You should use autoconfigure if you are defining the JVM server in a CICS bundle, as the server.xml configuration file cannot be included with the JVM profile in a CICS bundle.

4. Install and enable the JVMSERVER resource.

Results

The JVMSERVER reads the JVM profile and initializes itself based on the provided settings. If autoconfigure is enabled and a Liberty server configuration does not already exist, it will be created. If autoconfigure is not enabled and there is no configuration, or the configuration is incorrect, the JVMSERVER will become DISABLED and report an appropriate failure. On subsequent start up, the JVMSERVER will use the existing configuration and launch the Liberty server instance. When the JVMSERVER completes startup successfully, the JVMSERVER resource installs in the ENABLED state.

If an error occurs, for example, CICS is unable to find or read the JVM profile, the JVM server fails to initialize. The JVM server is installed in the DISABLED state and CICS issues error messages to the system log. See Troubleshooting Liberty JVM servers and Java web applications for help. To confirm that Liberty successfully started within your JVM server, consult the message.log file in the WLP_USER_DIR output directory on zFS.

Note: Enabling the JVM server starts the Liberty server and disabling the JVM server stops the Liberty server. Do not use the Liberty bin/server script to start or stop a Liberty server that is running in a JVM server.

Note: The current number of threads indicated by the JVM server will return a positive value even when no workload is running. This is because threads are now pooled within Liberty for efficiency. This value may increase or decrease spontaneously due to an internal algorithm.