Starting an OSGi or Liberty JVM server in CICS can seem like a daunting task at first, however once you get started you'll wonder what you were ever worried about. Creating and starting your JVM server can be done in a few simple steps. This article will show you exactly how to set up both an OSGi JVM server and Liberty JVM server in CICS in a way that even the most Java-phobic reader will find easy.
To follow the steps in this article you should already have performed the following:
- Setup CICS TS V5.1 or V5.2
- Have access to UNIX System Services (USS)
- Installed Java on z/OS using a supported 64-bit IBM SDK
About this task
In this article we'll take you through setting up CICS and zFS for using JVM servers. We'll then take you through all the steps required to get you started with a simple JVM server in CICS before showing you how to configure it for WebSphere Liberty Profile.
This article will also briefly explain some of the artifacts associated with setting up the JVM server, including JVM logs and file structures.
1. Getting your CICS region ready
The first step to running Java in CICS is to ensure the USS and Java environment is enabled in CICS. To do this you simply need to do the following
- Add the SDFJAUTH library to the CICS region's STEPLIB
- Set the USSHOME SIT parameter to the location where the CICS USS libraries are installed, in this article we assume this is /usr/lpp/cicsts/cicsts52
- Find out where your Java runtime is installed, for the purposes of this article we will use /usr/lpp/java/J7.1 as our example location.
2. zFS configuration
There are several zFS files used by the JVM server in CICS, both for configuration and logs. A number of these are created for you when you first start the server, however you will need to create a JVM profile yourself. This article will provide you with the required instructions to do so.
2.1 zFS configuration files
There are only 2 mandatory configuration files required to run a JVM server in CICS, they are:
- JVM profile - This is the configuration file for the JVM server, it must be EBCDIC encoded and contains the environment variables and JVM settings necessary to support the JVM server
- server.xml - This is the configuration file for the Liberty runtime, it must be encoded in utf-8 and is an XML based configuration file. It is normally autoconfigured on the first startup of the Liberty JVM server
The JVM profile is located using the JVMPROFILEDIR SIT parameter for your CICS region. CICS provides a set of fully commented examples in the USSHOME/JVMProfiles zFS directory. However in this example we will show you how to configure from scratch. We will use the JVMPROFILEDIR location /var/cicsts/jvmprofiles as our JVM profile directory.
The server.xml file is exclusive to Liberty JVM servers. This file describes the Liberty configuration you wish to use for your Liberty JVM server. If you create a Liberty JVM server for the first time with the auto-configure option turned on then this file will be created for you. We recommend that users start your Liberty JVM servers with this option turned on when you start one for the first time, and then turn it off for any subsequent restarts of that JVM server. This article will make use of auto-configure to create a server.xml file.
2.2 zFS output files
There are several output files used by the JVM server, such as the stdoud, stderr, JVM server trace and Liberty FFDC and messages logs. These are located using the WORK_DIR setting in the JVM profile. We will use the location /logs/cics/<applid>/<jvmserver> This means that for our example server called 'LIBERTY' on our CICS region with applid 'CICS1' the location will be: /logs/cics/CICS1/LIBERTY.
2.3 zFS file permissions
Access to USS files is controlled using the CICS region user ID and the POSIX file permission bits. You will need to ensure that the CICS region user ID has a USS segment, and either this user ID or a group it belongs has the following permissions:‹
- Execute access to all directories - This is required to enter any directory
- Read access to the JVM profile directory - to read the configuration
- Read and write access to the working directory - to create log files
Using our examples you can issue the following USS commands to set these permissions where <cicsgid> is the group ID that the CICS region user ID belongs to, and CICS1 is the APPLID of our CICS region and 'LIBERTY' is the name of our JVM server.
- chgrp <cicsgid> /var/cicsts/jvmprofiles
- chmod 750 /var/cicsts/jvmprofiles
- chgrp <cicsgid> /logs/cics/CICS1/
- chmod -R 770 /logs/cics
3. Creating a JVM server
We are now ready to create and start the JVM server. To begin, we need to create a JVM profile for our Liberty JVM server.
- Create an empty zFS file called LIBERTY.jvmprofile in the /var/cicsts/jmvprofiles directory using a USS file editor such as ISHELL or vi.
- Add the following 2 lines, note that the &APPLID and &JVMSERVER symbols will be dynamically resolved at runtime.
- Define a JVMSERVER definition using CEDA as shown:
- Set the Jvmprofile attribute to LIBERTY which is the name of the JVM profile prefix in zFS, as created in step 1.
OVERTYPE TO MODIFY CICS RELEASE = 0680CEDA ALter JVmserver( MYJVM )JVmserver : MYJVMGroup : MYGROUPDEScription ==> MY FIRST JVM SERVERStatus ==> Enabled Enabled | DisabledJvmprofile ==> LIBERTY (Mixed Case)Lerunopts ==> DFHAXROThreadlimit ==> 015 1-256PF 1 HELP 2 COM 3 END 6 CRSR 7 SBH 8 SFH 9 MSG 10 SB 11 SF 12 CNCL
- Install and enable the JVM server into your CICS region using CEDA, and check the status using the command CEMT I JVMSERVER. If the status shows enabled, then you know your OSGi JVM environment is working well.
If the JVM server starts then you have completed your first step and have successfully validated the Java environment in CICS. If it fails to enable, you should check the CSMT log and the stderr log in the zFS working directory for further errors.
4. Adding the Liberty runtime
Now that we know our Java environment in CICS is valid, we can add the WebSphere Liberty Profile to our JVM server.
Stop your JVM server using the command CEMT SET JVMSERVER(LIBERTY) DISABLED, and add the following lines to your JVM profile, replacing 12345 with the TCP/IP port you wish to use for the Liberty HTTP listener. We're now going to update your JVM profile to include the required parameters which add the WebSphere Liberty Profile to your JVM server.
WLP_INSTALL_DIR tells CICS where to find the user's installation of Liberty.
WLP_OUTPUT_DIR tells CICS where to put any server generated files, such as logs.
WLP_USER_DIR specifies a user directory for Liberty installations. Liberty will look for any shared resources or server configurations in this directory.
-Dcom.ibm.cics.jvmserver.wlp.server.name gives the Liberty JVM server a name. This is the name Liberty will use for itself in it's logs and files, meaning it will not automatically match your CICS JVM server definition name. We would recommend setting this value to be identical to the JVM server definition in order to avoid confusion.
-Dcom.ibm.cics.jvmserver.wlp.autoconfigure specifies whether or not the Liberty JVM server should configure itself automatically. This will create a server.xml file if used on first start up. After your first start up, you should turn this option off. To do simply change 'true' to 'false'.
When you next re-enable your JVM server in CICS using CEMT SET JVMSERVER(LIBERTY) ENABLED, your Liberty runtime infrastructure and configuration files will be generated automatically by CICS. Once the JVM server becomes enabled you have successfully started a Liberty JVM server. The output files for your Liberty JVM server will differ slightly to your OSGi JVM server. The Liberty specific zFS configuration and log files can still be found in the directory specified as WORK_DIR in your JVM profile. In our example the Liberty JVM server's configuration file can be found at:
Your Liberty JVM server also has it's own messages log file which contains any messages output by the Liberty JVM server or applications it's running. This file can be found at:
Both messages.log and server.xml are written to USS in ASCII. You can view and edit these files by using the 'Edit ASCII' option in the z/OS UNIX Directory List Utility panel in ISPF (usually option 3.17). To do so simply enter the name of the USS directory containing your server.xml file as your Pathname like so:
On the next panel, enter 'EA' next to your server.xml or messages.log file to edit in ASCII mode.
The file will then be opened in a readable format for you to view edit.
If you open your messages.log file you will see that Liberty has created a small number of messages while starting up. As well as checking the status of your Liberty JVM server in CICS after startup you can also search this log for the following message:
A CWWKF0011I: The server LIBERTY is ready to run a smarter planet.
This message is Liberty's way of telling you that the server has started and is ready for use. Another way to check your Liberty JVM server's status quickly is by using the homepage created by the JVM server. This page is a simple splash page which is displayed by Liberty when a browser attempts to access it's HTTP or HTTPS port without URI. You can get to this page by visiting the URL yourCicsHostName:YourLibertyPort
So for example your address may be: http://myLibertyHost:12345
5. What to do next
In the upcoming weeks we are hoping to bring you more information on how to get the most out of a Liberty JVM server in CICS, explaining how to set-up an effective development environment and write your first applications.
If you can't wait until then to get started then there are a number of resources you can use to get started with Liberty applications provided by both the Liberty teams and the CICS team.
5.1 Deploy the CICS Explorer example applications
IBM CICS Explorer includes a set of example applications to help demonstrate how web enabled applications in Liberty can be written to make use of CICS data structures and APIs. You can find the Liberty examples in the examples menu under 'Servlet & JSP'. You can find information in the IBM Knowledge Center on how to create and deploy the examples here for CICS TS V5.2:
5.2 Make use of the WebSphere samples
WebSphere's WASDev community website provides a number of tutorials, samples and guides for Liberty servers. A number of the guides contain API features which are not currently supported on CICS, however many are compatible with Liberty JVM servers running in CICS. Their site can be found here:
The WebSphere Liberty Profile team also have a fantastic redbook available which provides a number of guides for supported features which include working examples. You can get this redbook from the IBM Redbook site
You can find the list of features supported by CICS TS V5.2 in the IBM Knowledge Center