Chapter 2. Java Virtual Machine support in CICS
2.4 Analyzing programs for use in a continuous JVM
In 2.3.2, “Continuous JVM” on page 21, we discussed the application considerations that are required when using a continuous mode JVM. The main area that needs attention is the use of static variables in a program, with special attention paid on the reliance of static
initialization. To aid in the analysis of a program’s suitability for running in a continuous mode JVM, you can use the CICS JVM Application Isolation Utility to produce a report on the static usage in a program, or collection of programs. Supplied as part of the CICS TS 3.2 install, or available as a SupportPac CH1B, the CICS JVM Application Isolation Utility scans compiled Java programs and reports any updates to static variables.
Important: The resettable JVM mode was removed in CICS TS 3.2 and is not available in
any future CICS releases. It was intended as an intermediate solution for running applications that are not known to be safe for running in continuous mode JVM. With the introduction of Java 5, the resettable mode is no longer supported at the JVM level. Therefore, you must design and code new applications that can run in continuous mode, and be prepared to migrate existing code.
REUSE option in profile Can program invocations pass state? Relative performance Compatible with the shared class cache?
Single use NO N/A (JVM destroyed) Lowest (JVM initialized for
each use)
No
Continuous YES Yes High Yes
Attention: For CICS release CICS TS 2.2 and later, the utility is available as SupportPac
CH1B, which you can download from the IBM CICS SupportPac site:
2.4.1 Configuring the application isolation utility on UNIX System Services
The CICS JVM Application Isolation Utility that comes with the CICS TS 3.2 installation is located in the/usr/lpp/cicsts/cicsts32/utils/isolation directory (or the equivalent CICS install directory on your system) on Unix System Services. Example 2-4 shows the contents of this directory.Example 2-4 Contents of isolation directory
-rw-r--r-- 1 xxxxxx xxxxxxx 2368 Oct 28 09:35 DFHIsoUtil -rw-r--r-- 1 xxxxxx xxxxxxx 22655 Oct 28 09:35 dfhjaiu.jar
The file DFHIsoUtil is a shell script for running the utility. The file dfhjaiu.jar contains the compiled Java classes for the application. To run the DFHIsoUtil script, the CICS_HOME
environment variable needs to be set to where CICS directory resides on UNIX System Services, Example 2-5 shows how to do this.
Example 2-5 Setting the CICS_HOME environment variable
export CICS_HOME=/usr/lpp/cicsts/cicsts32
When running the DFHIsoUtil, you make sure that it has the appropriate execution permissions. The directory listing in Example 2-4 lists the permissions of both files as
-rw-r--r--. This means that they can both be read by everyone (user, group, and others), and modified by the user, but they cannot be executed. Because DFHIsoUtil is a script that we want to execute, update its permissions to look like -rwxr-xr-x. In Example 2-6, we show what happens when you try to run the script without execute permission, and then what happens after it is set.
Example 2-6 Setting execution permissions for DFHIsoUtil
./DFHIsoUtil: FSUM9209 cannot execute: reason code = ef076015: EDC5111I Permission denied.
# Now set the permissions using chmod: chmod +x DFHIsoUtil//(1)
# List the permissions of the updated file: ls -l DFHIsoUtil
-rwxr-xr-x 1 xxxxxx xxxxxxx 2368 Oct 28 09:35 DFHIsoUtil// (2)
# Now it can be run without error: ./DFHIsoUtil
CicsIsoUtil: CICS JVM Application Isolation Utility Copyright (C) IBM Corp. 2007
Usage: java -cp dfhjaiu.jar CicsIsoUtil [-options] filename [filename... filename] Where filename is the name of a Java class or jar file
to be inspected. Multiple files may be specified, or wildcard (glob) characters may be used.
Options may be:
-v -verbose enable verbose output -? -help display this help text
Chapter 2. Java Virtual Machine support in CICS 25
Notes on Example 2-6 on page 24:
chmod is a UNIX utility for modifying the permissions of files. Type man chmod in UNIX Systems Services to see more information about this command.
The value x signifies that execute permissions were added to DFHIsoUtil.
2.4.2 Generating reports on static updates
With the utility configured and ready to run, you can now use it to generate reports on the updating of statics within Java programs. As we discussed earlier, you can run the program against an individual .class file or a collection of .class files that are inside a .jar file.
Reporting updates to static variables
The easiest mistake to make is to rely on the static initialization of variables. Example 2-7 shows some code where the value of the count variable is set to 0 on static initialization of the class. In a single use JVM, this initialization occurs on every invocation of the program. However, when using a continuous JVM, static initialization happens only when the JVM is created, which means that multiple invocations of the program cause the value to continually increase. Without understanding this behavior, you might experience unexpected behavior during program execution.
Example 2-7 Updating a static variable in a program
public class HelloWorldStaticVariables { private static int count = 0;// (1) public static void main(String args[]) {
count++; }
}
Notes on Example 2-7:
Count gets set to 0 as part of the static initialization of the class, this only happens once, at the point the JVM is created.
Running CICS Java Application Isolation Utility program on your development platform: Because the CICS Java Application Isolation Utility is a Java program, you can
run it on your development platform (Linux, Windows, and so on):
1. Take a copy of dfhaiu.jar from UNIX Systems Services, and place it on your workstation using ftp binary mode transfer.
2. Making sure that Java is installed on your machine, bring up a command line window, and from the directory where the jar file now resides, type java -classpath
dfhjaiu.jar CicsIsoUtil
.jar file: A .jar file is simply a compressed file (.zip file) with a different extension. See this
Example 2-8 shows that report that running the CICS JVM Application Isolation Utility against this class produces.
Example 2-8 Report generated from the code in Example 2-7 on page 25
./DFHIsoUtil examples/HelloWorld/HelloWorldStaticVariables.class CicsIsoUtil: CICS JVM Application Isolation Utility
Copyright (C) IBM Corp. 2007
Reading class file: examples/HelloWorld/HelloWorldStaticVariables.class Method: public static void main(java.lang.String[])// (1)
Static fields written in this method: private static int count
Method: <clinit> (Class Initialization)// (2) Static fields written in this method: private static int count
Number of methods inspected : 3 Total static writes for this class: 2 Number of jar files inspected : 0 Number of class files inspected : 1
The report in Example 2-8 shows that there are two places where updates are made to static variables. In case (1) the static variable count is updated inside the main() method, in case
(2) the static variable is set on class initialization. Having found these instances of static updates, the code must be analyzed to determine if the behavior is problematic in a continuous JVM.
In the case of Example 2-7 on page 25, the static variable count is set to 0 only at the point when the JVM (and class) is created. On each invocation of the program within the same continuous JVM, the value of count is remembered from the last run and is incremented by 1. If this behavior is undesirable, a work around is to set count = 0 at the beginning of the
main() method. However, this still causes the same report to be generated, as shown in Example 2-8.
Reporting updates to the contents of static final Objects
A safe way to use static values in a program is to make them final, which means that the static variable instance cannot be changed in the program. Adding the final modifier to static instances of primitive Java types, and immutable objects, such as instances of String, make them safe for use in a continuous JVM and so they are not reported, as shown in
Example 2-8. However, this does not apply for all Java objects, for instance, even though the value of a static final object cannot be changed, this does not stop the contents of that object that is modified.
Example 2-9 on page 27 demonstrates this scenario using a
Hashtable
from the Java collections library. The Hashtable is created on static initialization of the class and is declared as final, which means that for the lifetime of this JVM the myHashtable variable will only ever point to that instance of Hashtable, that is, it is fixed and can never be changed. However, this does not stop the contents of this Hashtable being updated. Therefore this type of behavior is recognized by the CICS JVM Application Isolation Utility and reported accordingly.Chapter 2. Java Virtual Machine support in CICS 27
Example 2-9 Updating the contents of static final objects in a program
public class HelloWorldStaticObjects {
private static final Hashtable myHashtable = new Hashtable(); public static void main(String args[]) {
myHashtable.put("key", "value"); }
}
Example 2-10 shows the report that is produced when you run the CICS JVM Application Isolation Utility against this class.
Example 2-10 Using utility with a class that updates static final Object
./DFHIsoUtil examples/HelloWorld/HelloWorldStaticObjects.class CicsIsoUtil: CICS JVM Application Isolation Utility
Copyright (C) IBM Corp. 2007
Reading class file: examples/HelloWorld/HelloWorldStaticObjects.class Method: <clinit> (Class Initialization)// (1)
Static fields written in this method:
private static final java.util.Hashtable myHashtable Number of methods inspected : 3
Total static writes for this class: 1 Number of jar files inspected : 0 Number of class files inspected : 1
The report in Example 2-10 shows that a static object is created during class initialization. Even though the object is declared as final, its contents can still be updated and cached between subsequent program invocations. As discussed in 2.3.2, “Continuous JVM” on page 21, if used correctly, this caching of information can be beneficial for retrieving reference information. However if done unintentionally, these updates to static objects can generate unpredictable program behavior.