Configure the Liberty JVM server if you want to deploy Java EE applications such as EJBs,
JSP, JSF and servlets.
About this task
You have two ways of configuring a Liberty JVM server:
- Autoconfigure
- CICS® automatically creates and updates the configuration
file for Liberty, server.xml, from templates that are supplied in the CICS installation directory. Autoconfigure gets you started
quickly with a minimal set of configuration values in Liberty. To enable autoconfigure, set the JVM
system property, -Dcom.ibm.cics.jvmserver.wlp.autoconfigure property to
true. If you are defining the JVM server in a CICS bundle, set this option.
- Manually configuring
- This is the default setting. You supply the configuration files and all values. Manually
configuring is appropriate where you want to remain in full control of the Liberty server
configuration.
To define the JVM server, see Ways of defining CICS resources.
Procedure
- Create a JVMSERVER resource. If you want to
create a JVMSERVER resource within a CICS bundle, see Artifacts that can be deployed in bundles.
- 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 file name of the JVM profile, which is the file that holds the configuration options for the
JVM server. You do not need to specify the file type, .jvmprofile, here.
- 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 actual number of threads that are 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.
- 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.
- 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.
- 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
(Optional) Set CICS_WLP_MODE to choose the level of integration
between CICS and Liberty.
See JVM server options for more information about JVM
server options.
- Save your changes to the JVM profile. The JVM profile must be saved in EBCDIC file encoding on UNIX System Services and the file file type must be .jvmprofile.
- Create the Liberty server configuration.
Manually creating JVM servers is appropriate when the configuration files need to be carefully
controlled. For more information, see
Manually creating a Liberty server and
Manually tailoring server.xml.
Important: 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.
- 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 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.
CAUTION:
Do not use the Liberty
bin/server script to start or stop a Liberty server that is running in a JVM server.
Note: In
CICS integrated-mode Liberty, the current number of threads
indicated by the JVM server will return a positive value and can fluctuate even when no workload is
running. This is because threads are pooled within Liberty for efficiency.
What to do next
- Run the CICS Liberty default web application to verify
the Liberty JVM server is running by using the following URL:
http://server:port/com.ibm.cics.wlp.defaultapp/. For more information, see Configuring the CICS
Default Web Application.
- Specify any directories that contain native C dynamic link library (DLL) files, such as WebSphere® MQ. Middleware and tools that are
supplied by IBM or by vendors might require DLL files to be
added to the library path.
- If you want to run multiple Liberty JVM servers in a CICS region, add the following to the JVM profile of each additional Liberty JVM server:
WLP_ZOS_PLATFORM=FALSE. Only one security enabled Liberty JVM server is permitted
per CICS region. This is because CICS uses the z/OS® platform extensions
of Liberty for authentication and authorization. However, these z/OS platform aspects of Liberty are restricted to a single Liberty server within an address
space. By default, Liberty JVM servers start the z/OS
platform extensions, however only the first Liberty JVM server within a CICS region enables with security successfully.
- Add support for security. See Configuring security for a Liberty JVM server.
- Install the Java EE applications (EAR
files, WAR files, and EBA files), as described in Deploying a Java EE application in a CICS bundle to a Liberty JVM server.
- For more information on general Liberty set up see this overview on Liberty, Liberty overview.