Tuning Language Environment enclave storage for JVMs

As explained in Java™ Applications in CICS®, a JVM in CICS runs as a UNIX System Services process in a Language Environment® enclave created using the Language Environment preinitialization module, CEEPIPI, and it uses MVS™ Language Environment services rather than CICS Language Environment services. As a result, all storage obtained by the JVM is MVS storage, obtained by calls to MVS Language Environment services. This storage resides within the CICS address space but is not included in the CICS dynamic storage areas (DSAs).

Each JVM executes within its own Language Environment enclave, using storage allocations set by CICS. Java Applications in CICS explains how the storage heaps in the JVM are allocated from the Language Environment enclave heap storage.

The Language Environment enclave for each JVM needs to contain not only the storage heaps described in Tuning storage for individual JVMs, but also a basic amount of storage for each JVM. This basic storage cost represents the amount of storage in the Language Environment enclave that is used for the structure of the JVM, and when you calculate the total size of the JVM, the basic storage cost must be added to the storage that is used for the storage heaps.

The basic Language Environment run-time options used by CICS for a JVM enclave are shown in Table 13:

Table 13. Language Environment run-time options used by CICS for the JVM enclave
Language Environment run-time options Value set by CICS
Library heap storage that is not restricted to a location below 16MB.
ANYHEAP(4K,8176,ANY,FREE)
Library heap storage that must be located below 16MB.
BELOWHEAP(4096,2048,FREE)
Storage for user-controlled dynamically allocated variables.
HEAP(4M,1M,ANY,FREE,0K,4080)
Library stack storage
LIBS(8,900,FREE)
Start of changeLibrary routine stack frames that can reside anywhere in storageEnd of change Start of change
STACK(128K,128K,ANY,KEEP,
128K,128K)
End of change
Amount of storage reserved for the out-of-storage condition and the initial content of storage when allocated and freed.
STORAGE(,,,0K)
Note:
For information about Language Environment run-time options, see z/OS®: Language Environment Customization, SA22-7564.

You can override the Language Environment run-time options using the DFHJVMRO user-replaceable module, which is described in the CICS Customization Guide. The default Language Environment storage settings that control the initial size of, and incremental additions to, the Language Environment enclave heap storage can make inefficient use of MVS storage. The storage settings that CICS supplies in DFHJVMRO are more efficient. You can also modify these settings to match more closely with the storage use of your JVMs. To improve the use of MVS storage, you are recommended to use DFHJVMRO to set the initial allocation for the amount of Language Environment enclave heap storage to a value that approximates to the storage actually used by your Java applications that run in JVMs, using this as an initial heap size. Note that the settings that you make using DFHJVMRO apply to all the JVMs in your CICS region (with the exception of the master JVM that initializes the shared class cache), so you should consider the different storage heap sizes and basic storage costs that JVMs with different profiles might have. As noted in Managing your JVM pool for performance, the basic storage cost for a standalone JVM is significantly larger than the basic storage cost for a worker JVM.

You can use the CICS statistics to see how much Language Environment enclave heap storage is used by your JVMs. The field "Peak Language Environment heap storage used" in the JVM Profile statistics shows the peak (or high water mark) amount of Language Environment enclave heap storage that was actually used by a JVM with the specified execution key and profile. Collecting this statistic affects the performance of JVMs, so you should not carry out this process in a production environment. To obtain this information:

  1. Use the EXEC CICS INQUIRE JVMPROFILE command to identify each of the JVM profiles in use in your CICS region. (There is no CEMT equivalent for this command.)
  2. Specify the option LEHEAPSTATS=YES in each of the JVM profiles that you have identified. Note that you do not need to include the JVM profile that is used for the master JVM that initializes the shared class cache, because DFHJVMRO is not used for the master JVM. The CICS-supplied sample JVM profile for the master JVM is DFHJVMCC. If a JVM profile has only been used for the master JVM, it is not found by the EXEC CICS INQUIRE JVMPROFILE command.
  3. Purge your JVMs using the CEMT SET JVMPOOL PHASEOUT command (or the equivalent EXEC CICS command), around the time of a statistics reset (either before or immediately afterwards). This ensures that the statistics collected in the next statistics interval are a more accurate reflection of the storage usage for your JVMs. It also ensures that your JVMs will be re-created using the LEHEAPSTATS=YES option.
  4. Run a representative sample of the transactions that use your JVMs. When you have finished, either collect the JVM profile statistics using the EXEC CICS COLLECT STATISTICS JVMPROFILE or CEMT PERFORM STATISTICS JVMPROFILE command, or view the JVM profile statistics that have been collected during the statistics interval.
  5. Remove the option LEHEAPSTATS=YES from your JVM profiles, or change it to NO (which is the default). Purge your JVMs using the CEMT SET JVMPOOL PHASEOUT command to ensure that they are re-created with the option LEHEAPSTATS=NO.
  6. Examine the field "Peak Language Environment heap storage used" in the JVM Profile statistics for each JVM profile. Use this value to set as the initial heap size in DFHJVMRO. If the peak amount of storage used varies between JVM profiles, select a suitable value based on the relative usage of each JVM profile. Try to select a value that is close to the storage used by most of your JVMs, bearing in mind that Language Environment can make additions to the heap storage, but it cannot remove unwanted storage that is given in the initial allocation.

An alternative method of identifying a suitable value for the initial allocation for the amount of Language Environment enclave heap storage, is to use the RPTO(ON) and RPTS(ON) options in DFHJVMRO to obtain storage reports. These options increase CPU costs, so they should not be used in a production environment. DFHJVMRO cannot identify the JVM profile to which each storage report applies, so you should use this procedure for only one JVM profile at a time, by making sure you are using transactions that request only that JVM profile.

To obtain storage reports for your JVMs:

  1. Set the RPTO(ON) and RPTS(ON) options in DFHJVMRO. These options are within comments in the supplied source of DFHJVMRO. Specifying these options causes Language Environment to report on the storage options set, and to write a storage report showing the actual storage used.
  2. Purge any JVMs in your JVM pool using the CEMT SET JVMPOOL PHASEOUT command (or the equivalent EXEC CICS command), to ensure that they are re-created using the RPTO(ON) and RPTS(ON) options.
  3. Run a representative sample of the transactions that use JVMs with the JVM profile that you want to examine. (The JVM profile for a program is named in the PROGRAM resource definition.) When you have finished, remove the RPTO(ON) and RPTS(ON) options from DFHJVMRO, then purge your JVMs using the CEMT SET JVMPOOL PHASEOUT command (or the equivalent EXEC CICS command). The storage reports are written when each JVM ends. The storage reports include a recommendation for the initial Language Environment enclave heap storage (shown as "Total heap storage used (sugg. initial size)"), which is equal to the total amount of Language Environment enclave heap storage that was used by the JVM.
  4. Repeat the procedure for JVMs with each different JVM profile that is used in your CICS region, with the exception of the JVM profile that is used for the master JVM that initializes the shared class cache, because DFHJVMRO is not used for the master JVM. Examine all the sets of storage reports to check for any variations in the amount of storage used. You can then select a suitable value to be set as the value for the initial Language Environment enclave heap storage, using DFHJVMRO. Try to select a value that is close to the storage used by most of your JVMs, bearing in mind that Language Environment can make additions to the heap storage, but it cannot remove unwanted storage that is given in the initial allocation.

For example, if you receive the following storage report:

HEAP statistics:
   Initial size:                                     31457280
   Increment size:                                    2097152
   Total heap storage used (sugg, initial size):     38837096
   Successful Get Heap requests:                       155034
   Successful Free Heap requests:                      108642
   Number of segments allocated:                            7
   Number of segments freed:                                0

you can set these values for Language Environment enclave heap storage, using DFHJVMRO:

HEAP(38M,1M,ANYWHERE,FREE,0K,4080)

The amounts of storage required for a JVM in a Language Environment enclave may require changes to installation exits, IEALIMIT or IEFUSI, which you use to limit the region size. Note that running with a default IEFUSI and specifying REGION=0M will result in a region size of 32M, which is not enough to support a JVM.

A possible approach is to have a JVM owning region (JOR), to which all JVM program executions are routed. Such a region would run only JVM workloads, thereby allowing you to minimize the amount of CICS DSA storage required, and allow the maximum amount of MVS storage to be allocated for use by JVMs.

Related concepts
The structure of a JVM
Storage heaps in a JVM

Related tasks
Using DFHJVMRO to modify the Language Environment enclave for a JVM
Java applications using a Java virtual machine (JVM): improving performance
Tuning storage for individual JVMs
Tuning the z/OS shared library region
Managing your JVM pool for performance
Tuning for enterprise beans
Managing your JVMs
[[ Contents Previous Page | Next Page Index ]]