Java Virtual Machine sample definition files

CICS® launches a JVM to execute a Java™ program that specifies a JVM in its program resource definition. The JVM is created using options specified in a series of text files:

CICS provides samples of all these, as described in the following sections. "Setting up JVM profiles and JVM properties files" in Java Applications in CICS has more information about these files and the relationships between them.

JVM profiles

CICS provides five sample JVM profiles in the partitioned dataset named SDFHENV. Each sample JVM profile can be used to create a different type of JVM. The sample JVM profiles are as follows:

Table 14. CICS-supplied sample JVM profiles
JVM profile Purpose
DFHJVMPR The default JVM profile if no other is specified on a PROGRAM resource definition. JVM is resettable. Does not use the shared class cache.
DFHJVMPC JVM is resettable and uses the shared class cache.
DFHJVMPS JVM is single-use. Not recommended for enterprise beans.
DFHJVMCC Profile for the master JVM that initializes the shared class cache.
DFHJVMCD (reserved for the use of CICS) Profile for CICS-defined programs. Do not use for your own applications. Only change as necessary.

In their supplied form, the JVM profiles are defined with JVMPROPS and LIBPATH parameters that use the symbols &CICS_DIRECTORY, &JAVA_HOME. These profiles are customized when you install CICS TS and run the DFHIJVMJ job, as follows:

&CICS_DIRECTORY
This symbol is replaced with the value you specify on the USSDIR parameter in the DFHISTAR installation job. The default is cicsts31, resulting, for example, in directory paths of the form /pathprefix/usr/lpp/cicsts/cicsts31/lib on LIBPATH.
&JAVA_HOME
This symbol is replaced with the value you specify on the JAVADIR parameter in the DFHISTAR installation job. The default is java142/J1.4, resulting in directory paths of the form /pathprefix/usr/lpp/java142/J1.4/bin and /pathprefix/usr/lpp/java142/J1.4/bin/classic on LIBPATH.

The string java142/J1.4 is what you should specify on JAVADIR for use with the IBM Software Developer Kit for z/OS, Java 2 Technology Edition, Version 1.4.2.

Note:
The extra // characters on each side of the symbols are removed during symbol substitution.

After you have run DFHIJVMJ to substitute your own values for the symbol names, the customized profiles are written to the directory /pathprefix/usr/lpp/cicsts/cicsts31/JVMProfiles in the hierarchical file store (HFS), where cicsts31 is the value that you chose for the CICS_DIRECTORY variable used by the DFHIJVMJ job during CICS installation. Because the JVM profiles are stored in HFS, CICS requires access to z/OS® UNIX System Services, and to directories and files in HFS, in order to create JVMs. "Giving CICS regions access to z/OS UNIX System Services and HFS directories and files" in Java Applications in CICS explains how to give CICS the access it requires.

"Setting up JVM profiles and JVM properties files" in Java Applications in CICS tells you how to enable CICS to locate the JVM profiles, how to choose an appropriate JVM profile for your Java programs, and how to customize the supplied sample JVM profiles to your system's requirements. In particular, if you place the JVM profiles in a location other than the default directory /pathprefix/usr/lpp/cicsts/cicsts31/JVMProfiles, or if you choose a different name during CICS installation for this directory, you need to change the system initialization parameter JVMPROFILEDIR to specify the correct directory, or use UNIX soft links to link to the JVM profiles from the default directory. You also need to ensure that CICS has access to the HFS directory where the JVM profiles are stored.

Note that the JVM profiles DFHJVMPR and DFHJVMCD, and their associated JVM properties files, must always be available to CICS. DFHJVMPR is used if a Java program is defined as using a JVM but no JVM profile is specified, and it is used for sample programs. DFHJVMCD is used by CICS-defined programs, including the default request processor program (DFJIIRP) and the program that CICS uses to publish and retract deployed JAR files (DFJIIRQ, the CICS-key equivalent of DFJIIRP). Both these JVM profiles must therefore either be present in the directory that is specified by JVMPROFILEDIR, or linked to by means of UNIX soft links from that directory, and they must be configured correctly so that they can be used in your CICS region.

You can edit the JVM profiles with any text editor to customize them for your system. "Choosing a JVM profile and JVM properties file" in Java Applications in CICS tells you about some options that you might want to change, and the CICS System Definition Guide has the full lists of options that you can specify using JVM profiles and JVM properties files. For single-use JVMs (that is, with a JVM profile that specifies the option REUSE=NO or the older option Xresettable=NO), instead of customizing the JVM profile, you can override the options in it, using the user-replaceable program DFHJVMAT. Normally, a JVM profile provides sufficient flexibility to configure a JVM as required. If you find that you need to make unusual modifications, the CICS Customization Guide has more information about using DFHJVMAT.

As JVM profiles and JVM properties files are HFS files, case is important. CICS does not automatically convert the name of a JVM profile or JVM properties file to upper case. When you use the name of a JVM profile or JVM properties file anywhere in CICS, you must enter it using the same combination of upper and lower case characters that is present in the HFS file name.

JVM properties files

You use the JVMPROPS option in a JVM profile to specify the full path of the JVM properties file that is associated with the profile. CICS provides five sample JVM properties files in the SDFHENV partitioned data set, which are designed to support their corresponding JVM profile:

Table 15. CICS-supplied sample JVM properties files
JVM profile Associated JVM properties file
DFHJVMPR dfjjvmpr.props
DFHJVMPC dfjjvmpc.props
DFHJVMPS dfjjvmps.props
DFHJVMCC dfjjvmcc.props
DFHJVMCD (reserved for the use of CICS) dfjjvmcd.props

The sample JVM properties files are defined with the &CICS_DIRECTORY symbol, which is replaced with your own value when you run the DFHIJVMJ installation job. When the symbol substitution is complete, the customized JVM properties files are copied to the HFS directory /pathprefix/usr/lpp/cicsts/cicsts31/props/, where cicsts31 is the value that you chose for the CICS_DIRECTORY variable used by the DFHIJVMJ job during CICS installation.

The JVMPROPS option on a JVM profile references a JVM properties file by using its full path name. The CICS-supplied sample JVM profiles reference the sample JVM properties files as follows:

JVMPROPS=/pathprefix/usr/lpp/cicsts/cicsts31/props/dfjjvmpx.props

where dfjjvmpx.props is the name of the sample JVM properties file that matches with the sample JVM profile. If you change the name or location of a JVM properties file, or create your own JVM properties file, you need to change the JVMPROPS option to specify the correct path name in all the JVM profiles that reference that JVM properties file. You also need to ensure that CICS has access to the HFS directory where the JVM properties file is stored.

As for the JVM profiles, you can edit the JVM properties files with any text editor to customize them for your system. "Choosing a JVM profile and JVM properties file" in Java Applications in CICS tells you about some options that you might want to change, and the CICS System Definition Guide has the full lists of options that you can specify using JVM properties files. Remember that CICS does not automatically convert the name of a JVM properties file to upper case, so when you use the name of a JVM profile or JVM properties file anywhere in CICS, you must enter it using the same combination of upper and lower case characters that is present in the HFS file name.

Java 2 security policy for EJBs

CICS provides a sample Java 2 security policy that you can use, or modify to suit your own requirements. The sample policy is named dfjejbpl.security, and it defines security properties that are suitable for JVMs that are used by enterprise beans. The sample policy is supplied on the distribution tape in SDFHENV. During the installation process, the policy is customized and written to /pathprefix/usr/lpp/cicsts/cicsts31/lib/ security/dfjejbpl.policy, where cicsts31 is a user-defined value specified on the USSDIR parameter in the DFHISTAR installation job. "Protecting Java applications in CICS" in Java Applications in CICS tells you what changes you need to make to the sample JVM properties files to enable Java 2 security, how to set up a security policy file, and about the CICS-supplied sample security policy file dfjejbpl.policy.

Related tasks
Verifying your Java components installation
[[ Contents Previous Page | Next Page Index ]]